# Get the downtime ledger — API reference > Returns outage timelines, evidence coverage and report provenance for the selected window, with optional file formats. Source: https://upfour.io/docs/api/reports/get-the-downtime-ledger [Developers](https://upfour.io/docs/api.md)/[Reports](https://upfour.io/docs/api/reports.md) Returns outage timelines, evidence coverage and report provenance for the selected window, with optional file formats. GET https://app.upfour.io/v1/reports/downtime-ledger scope report.read stable returns 200 ## Parameters | Field | Type | Description | | --- | --- | --- | | `format` optional | string one of`csv` `json` `pdf` `xlsx` | query parameter · Without it the answer is the JSON envelope; with it the answer is a file download of that format. | | `preset` optional | string one of`24h` `7d` `30d` `90d` `mtd` `last_month` `qtd` `ytd` | query parameter · Reporting window; `period` is accepted as an alias. Without `preset`, `from` and `to` the window is the last 30 days. The window is cut to the plan's history. | | `from` optional | string | query parameter · Start of the window: an RFC 3339 timestamp or a date (`YYYY-MM-DD`, in `tz`). Replaces `preset`. | | `to` optional | string | query parameter · End of the window, same formats as `from`; a date means the end of that day. Defaults to now. | | `tz` optional | string | query parameter · IANA time zone for calendar presets and dates. Defaults to the Company's report time zone. | | `lang` optional | string one of`en` `de` default `"en"` | query parameter · Language of the report text. | | `monitor_id` optional | uuid | query parameter · Only this monitor; repeat the parameter or send a comma-separated list for several. | | `severity` optional | string | query parameter · Incident reports only: keep incidents of this severity; repeat the parameter or send a comma-separated list for several. | | `q` optional | string | query parameter · Case-insensitive text: keeps monitors whose name, or incidents whose title, contains it. | | `business_hours` optional | string | query parameter · Count only these hours in SLA and response-time reports, for example `mon-fri,09:00-17:00` (several groups separated by `;`). The hours are read in `tz`, or in UTC when `tz` is not sent. | | `client_id` optional | uuid | query parameter · Report on one client. | | `all_clients` optional | boolean | query parameter · `true` includes all clients; without `client_id` the report covers the Company level. | ## Returns A successful request returns `200` with application/json, application/pdf, application/vnd.openxmlformats-officedocument.spreadsheetml.sheet, text/csv. Response fields 1 top-level fields | Field | Type | Description | | --- | --- | --- | | `data` | ReportDocument | | | ReportDocument · 89 fields FieldTypeDescription `branding` ReportDocumentBranding ReportDocumentBranding · 8 fields FieldTypeDescription `accent_color_hex` string `footer_text` string `logo_data_url` string `logo_url` string `org_name` string `primary_color_hex` string `watermark` string `website_url` string `content_hash` string Fingerprint of the content; GET /reports/verify/{hash} confirms it. `generated_at` string (date-time) `kpis` ReportKPI[] · nullable Each item · 10 fields FieldTypeDescription `label` string `value` string Formatted for display, for example "99.94 %". `delta` ReportKPIDelta ReportKPIDelta · 4 fields FieldTypeDescription `abs` number `direction` string one of`up` `down` `flat` `good` boolean `pct` number `key` string `raw` any The machine-readable value (a number, mostly); absent when there is no data. `unit` string `org` ReportCompany ReportCompany · 2 fields FieldTypeDescription `id` uuid `name` string `range` ReportRange ReportRange · 5 fields FieldTypeDescription `from` string (date-time) `to` string (date-time) `clamped` boolean true when the window was cut to the plan's history. `preset` string one of`24h` `1d` `7d` `30d` `90d` `mtd` `last_month` `qtd` `ytd` `timezone` string `sections` ReportSection[] · nullable Each item · 20 fields FieldTypeDescription `heading` string `charts` ReportChart[] Each item · 9 fields FieldTypeDescription `categories` string[] · nullable `kind` string one of`line` `bar` `donut` `stacked_bar` `heatmap` `series` ReportChartSeries[] · nullable Each item · 4 fields FieldTypeDescription `data` number[] · nullable `name` string `color` string `dash` boolean `title` string `y_unit` string `note` string `tables` ReportTable[] Each item · 7 fields FieldTypeDescription `columns` ReportColumn[] · nullable Each item · 4 fields FieldTypeDescription `header` string `align` string one of`left` `right` `center` `key` string `kind` string one of`text` `number` `percent` `duration` `timestamp` `rows` ReportCell[][] · nullable `title` string `title` string `type` string one of`executive_summary` `monitor_report` `monitor_sla` `downtime_ledger` `incident_analytics` `response_time` `trends` `client` ReportClient ReportClient · 3 fields FieldTypeDescription `id` uuid `name` string `logo_data_url` string `coverage` ReportCoverage ReportCoverage · 4 fields FieldTypeDescription `observed_days` integer `total_days` integer `partial_buckets` boolean `unavailable` boolean `date_format` string one of`day_month_year` `month_day_year` `iso` `lang` string one of`en` `de` `narrative` string `period` string `provenance` ReportProvenance ReportProvenance · 13 fields FieldTypeDescription `data_sources` string[] · nullable Where the figures come from, for example hot:check_results or cold:check_result_archive_daily_stats. `tool` string `hot_window` ReportRange ReportRange · 5 fields FieldTypeDescription `from` string (date-time) `to` string (date-time) `clamped` boolean true when the window was cut to the plan's history. `preset` string one of`24h` `1d` `7d` `30d` `90d` `mtd` `last_month` `qtd` `ytd` `timezone` string `manifests` ReportArchiveManifest[] Each item · 4 fields FieldTypeDescription `max_created_at` string (date-time) `min_created_at` string (date-time) `sha256` string `storage_key` string `sla` ReportSLAAssessment ReportSLAAssessment · 6 fields FieldTypeDescription `evaluated` integer `inconclusive` integer `met` integer `monitors` integer `no_data` integer `partial` integer `subtitle` string | | | ## Errors Only the errors this operation can return. Every error uses the [same envelope](https://upfour.io/docs/api/responses.md). | Status | Code | Meaning | | --- | --- | --- | | 400 | [bad_request](https://upfour.io/docs/api/errors#code-bad_request) | The request is malformed or fails validation. | | 403 | [permission_denied](https://upfour.io/docs/api/errors#code-permission_denied) | The credentials do not permit this action. | Every call can also return `unauthorized` (401), `rate_limit_exceeded` (429) or `internal_error` (500 / 502). See [Responses and errors](https://upfour.io/docs/api/responses.md). [PreviousGet the service-level report](https://upfour.io/docs/api/reports/get-the-service-level-report.md) [NextGet report trends](https://upfour.io/docs/api/reports/get-report-trends.md) ## Request ### cURL ```bash curl -s "https://app.upfour.io/v1/reports/downtime-ledger" \ -H "Authorization: Bearer $UP4_API_KEY" ``` ### JavaScript ```javascript const res = await fetch("https://app.upfour.io/v1/reports/downtime-ledger", { headers: { Authorization: `Bearer ${process.env.UP4_API_KEY}`, }, }); console.log(res.status, await res.json()); ``` ### Python ```python import os import requests res = requests.get( "https://app.upfour.io/v1/reports/downtime-ledger", headers={"Authorization": f"Bearer {os.environ['UP4_API_KEY']}"}, ) print(res.status_code, res.json()) ``` ### Go ```go package main import ( "fmt" "io" "net/http" "os" ) func main() { req, _ := http.NewRequest("GET", "https://app.upfour.io/v1/reports/downtime-ledger", nil) req.Header.Set("Authorization", "Bearer "+os.Getenv("UP4_API_KEY")) res, err := http.DefaultClient.Do(req) if err != nil { panic(err) } defer res.Body.Close() out, _ := io.ReadAll(res.Body) fmt.Println(res.StatusCode, string(out)) } ``` ### PHP ```php true, CURLOPT_HTTPHEADER => [ "Authorization: Bearer " . getenv("UP4_API_KEY"), ], ]); $response = curl_exec($ch); echo curl_getinfo($ch, CURLINFO_RESPONSE_CODE), " ", $response, "\n"; curl_close($ch); ``` ## Response ### 200 ```json { "data": { "branding": { "accent_color_hex": "#294E9E", "footer_text": "Acme GmbH", "org_name": "Acme GmbH", "primary_color_hex": "#294E9E" }, "content_hash": "721378bc96ef2ddece4a66b447ba60d6a1266860d9cb23f4e0e6c152f30279cb", "coverage": { "observed_days": 1, "total_days": 31 }, "date_format": "day_month_year", "generated_at": "2026-10-27T09:00:00Z", "kpis": [ { "key": "outages_full_fidelity", "label": "Outages (full-fidelity)", "raw": 0, "value": "0" }, { "key": "downtime_full_fidelity", "label": "Downtime (full-fidelity)", "raw": 0, "unit": "s", "value": "—" }, { "key": "failed_checks", "label": "Failed checks", "raw": 0, "value": "0" }, { "key": "archive_manifests", "label": "Archive manifests", "raw": 0, "value": "0" } ], "lang": "en", "org": { "id": "00000000-0000-4000-8000-000000000001", "name": "Acme GmbH" }, "period": "27 Sep 2026 09:00:00 - 27 Oct 2026 09:00:00 (end exclusive) · UTC", "provenance": { "data_sources": [ "hot:check_results", "cold:check_result_archive_daily_stats" ], "hot_window": { "from": "2026-10-19T16:55:00Z", "to": "2026-10-27T09:00:00Z" }, "tool": "up4-reporting/0.1.0" }, "range": { "from": "2026-09-27T09:00:00Z", "preset": "30d", "timezone": "UTC", "to": "2026-10-27T09:00:00Z" }, "sections": [ { "heading": "Outage timeline", "note": "Each full-fidelity row is a maximal run of consecutive failed checks (gap-and-island over check_results.was_successful). Cold rows are reconstructed from the daily archive — exact timestamps and error samples are no longer retained for those days; verify them against the archive manifest below.", "tables": [ { "columns": [ { "header": "Monitor", "key": "monitor", "kind": "text" }, { "header": "Start (UTC)", "key": "start_utc", "kind": "timestamp" }, { "header": "End (UTC)", "key": "end_utc", "kind": "timestamp" }, { "align": "right", "header": "Duration", "key": "duration", "kind": "duration" }, { "header": "Regions", "key": "regions", "kind": "text" }, { "align": "right", "header": "Failed checks", "key": "failed_checks", "kind": "number" }, { "header": "Sample errors", "key": "sample_errors", "kind": "text" }, { "header": "Data source", "key": "data_source", "kind": "text" } ], "rows": null, "title": "Outage timeline" } ] }, { "heading": "Evidence summary", "note": "No archive manifests cover this window yet — the cold portion is summarised from daily aggregates only. The full-fidelity portion is backed directly by the live check_results store." } ], "subtitle": "Timestamped outage evidence · last 30 days", "title": "Downtime ledger — Acme GmbH", "type": "downtime_ledger" } } ``` ### 400 ```json { "error": { "code": "bad_request", "message": "The request is malformed or fails validation.", "request_id": "req_…" } } ``` ### 403 ```json { "error": { "code": "permission_denied", "message": "The credentials do not permit this action.", "request_id": "req_…" } } ```