Get the downtime ledger

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

Authorization

AuthorizationA pls_ key. It stays in this browser tab. Needs report.read.

Query

formatqueryWithout it the answer is the JSON envelope; with it the answer is a file download of that format. presetqueryReporting 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. fromqueryStart of the window: an RFC 3339 timestamp or a date (YYYY-MM-DD, in tz). Replaces preset. toqueryEnd of the window, same formats as from; a date means the end of that day. Defaults to now. tzqueryIANA time zone for calendar presets and dates. Defaults to the Company's report time zone. langqueryLanguage of the report text. monitor_idqueryOnly this monitor; repeat the parameter or send a comma-separated list for several. severityqueryIncident reports only: keep incidents of this severity; repeat the parameter or send a comma-separated list for several. qqueryCase-insensitive text: keeps monitors whose name, or incidents whose title, contains it. business_hoursqueryCount 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_idqueryReport on one client. all_clientsquerytrue includes all clients; without client_id the report covers the Company level.

Sent directly from your browser to https://app.upfour.io/v1. Mutating calls get an automatic Idempotency-Key when the field is empty.

Request

Responsenot sent yet

Fill in a key and press Send request (⌘↵).
The answer appears here.

scope report.read stable returns 200

Parameters

Field	Type	Description
`format` optional	string one of`csvjsonpdfxlsx`	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`24h7d30d90dmtdlast_monthqtdytd`	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`ende` 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

Field Type Description

branding ReportDocumentBranding

ReportDocumentBranding · 8 fields

Field	Type	Description
`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

Field Type Description

label string

value string Formatted for display, for example "99.94 %".

delta ReportKPIDelta

ReportKPIDelta · 4 fields

Field	Type	Description
`abs`	number
`direction`	string one of`updownflat`
`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

Field	Type	Description
`id`	uuid
`name`	string

range ReportRange

ReportRange · 5 fields

Field	Type	Description
`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`24h1d7d30d90dmtdlast_monthqtdytd`
`timezone`	string

sections ReportSection[] · nullable

Each item · 20 fields

Field Type Description

heading string

charts ReportChart[]

Each item · 9 fields

Field Type Description

categories string[] · nullable

kind string one oflinebardonutstacked_barheatmap

series ReportChartSeries[] · nullable

Each item · 4 fields

Field	Type	Description
`data`	number[] · nullable
`name`	string
`color`	string
`dash`	boolean

title string

y_unit string

note string

tables ReportTable[]

Each item · 7 fields

Field Type Description

columns ReportColumn[] · nullable

Each item · 4 fields

Field	Type	Description
`header`	string
`align`	string one of`leftrightcenter`
`key`	string
`kind`	string one of`textnumberpercentdurationtimestamp`

rows ReportCell[][] · nullable

title string

type string one ofexecutive_summarymonitor_reportmonitor_sladowntime_ledgerincident_analyticsresponse_timetrends

client ReportClient

ReportClient · 3 fields

Field	Type	Description
`id`	uuid
`name`	string
`logo_data_url`	string

coverage ReportCoverage

ReportCoverage · 4 fields

Field	Type	Description
`observed_days`	integer
`total_days`	integer
`partial_buckets`	boolean
`unavailable`	boolean

date_format string one ofday_month_yearmonth_day_yeariso

lang string one ofende

narrative string

period string

provenance ReportProvenance

ReportProvenance · 13 fields

Field Type Description

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

Field	Type	Description
`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`24h1d7d30d90dmtdlast_monthqtdytd`
`timezone`	string

manifests ReportArchiveManifest[]

Each item · 4 fields

Field	Type	Description
`max_created_at`	string (date-time)
`min_created_at`	string (date-time)
`sha256`	string
`storage_key`	string

sla ReportSLAAssessment

ReportSLAAssessment · 6 fields

Field	Type	Description
`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.

Status	Code	Meaning
400	`bad_request`	The request is malformed or fails validation.
403	`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.

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())

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 $ch = curl_init("https://app.upfour.io/v1/reports/downtime-ledger"); curl_setopt_array($ch, [ CURLOPT_RETURNTRANSFER => 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);

{ "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" } }