Get uptime report — StatusDashboard Docs

GET /app/reports/uptime

Returns an on-demand monthly uptime report for the authenticated tenant. The response is the input for the admin console PDF export.

Admin role and the uptimeReports plan capability are required.

Request

See API Basics for required headers.

Query parameters

Provide exactly one of dashboardId or componentId — not both, not neither.

Name	Type	Required	Description
`dashboardId`	UUID	scope	Whole-dashboard mode: status dashboard to report on. Must belong to the authenticated org. Mutually exclusive with `componentId`.
`componentId`	UUID	scope	Single-component mode: org-owned component (`CMP#`). Not limited to dashboard wiring. Mutually exclusive with `dashboardId`.
`year`	integer	yes	Calendar year (`2000`–`2100`).
`month`	integer	yes	Calendar month (`1`–`12`).
`timezone`	string	yes	IANA timezone (max 64 chars), e.g. `America/Los_Angeles`.
`includeMaintenance`	boolean	no	Default `false`. When `true`, maintenance contributes to downtime. Accepts `"true"` or `"false"`.

Future months (month start strictly after today in the given timezone) return 400.

Sample requests

Whole dashboard

curl "https://api.statusdashboard.com/app/reports/uptime?dashboardId=a1b2c3d4-e5f6-7890-abcd-ef1234567890&year=2026&month=3&timezone=America/Los_Angeles&includeMaintenance=false" \
  -H "Authorization: Bearer bcf847abf5c6:def456"

Single component (dashboard is null in the response)

curl "https://api.statusdashboard.com/app/reports/uptime?componentId=c1b2c3d4-e5f6-7890-abcd-ef1234567890&year=2026&month=3&timezone=America/Los_Angeles" \
  -H "Authorization: Bearer bcf847abf5c6:def456"

Sample response (dashboard scope)

Status: 200 OK

{
  "tenantName": "Acme Corp",
  "dashboard": {
    "id": "a1b2c3d4-e5f6-7890-abcd-ef1234567890",
    "name": "Production Status"
  },
  "period": {
    "year": 2026,
    "month": 3,
    "timezone": "America/Los_Angeles",
    "startUtc": "2026-03-01T08:00:00.000Z",
    "endUtc": "2026-04-01T06:59:59.999Z"
  },
  "options": {
    "includeMaintenance": false,
    "scope": "dashboard",
    "componentId": null,
    "dashboardId": "a1b2c3d4-e5f6-7890-abcd-ef1234567890"
  },
  "generatedAt": "2026-03-15T17:22:01.234Z",
  "summary": {
    "uptimePercent": 99.12,
    "downtimeMinutes": 380,
    "periodMinutes": 43200
  },
  "components": [
    {
      "id": "c1…",
      "name": "API Gateway",
      "uptimePercent": 98.5,
      "downtimeMinutes": 648,
      "periodMinutes": 43200,
      "events": [
        {
          "id": "e1…",
          "title": "Elevated API errors",
          "eventType": "incident",
          "startTime": "2026-03-10T15:00:00.000Z",
          "endTime": "2026-03-10T18:30:00.000Z",
          "durationMinutesInPeriod": 210
        }
      ]
    }
  ]
}

Component scope

When componentId is supplied, dashboard is null, options.scope is "component", and components contains a single entry.

Response fields

Field	Description
`tenantName`	Organization display name.
`dashboard`	Dashboard id and name in dashboard scope; `null` in component scope.
`period`	Selected month boundaries in UTC plus the request timezone.
`options.scope`	`"dashboard"` or `"component"`.
`options.componentId`	Component UUID when scoped to one component; otherwise `null`.
`options.dashboardId`	Dashboard UUID in dashboard scope; otherwise `null`.
`summary.uptimePercent`	Rolled-up uptime (unweighted mean for multi-component dashboard scope).
`summary.downtimeMinutes`	Wall-clock downtime minutes for a single component (or `0` when the dashboard has no components). `null` for multi-component dashboard rollups — downtime is not summed across components.
`components[].events`	Contributing published events sorted by `startTime` ascending.
`components[].events[].startTime`	Original event interval start (not period-clipped).
`components[].events[].endTime`	Original event interval end; open events use `generatedAt`; final events without `endTime` use `resolvedAt` when present.
`components[].events[].durationMinutesInPeriod`	Downtime minutes for this event clipped to the report month (used for display; component % uses merged intervals).

Empty months return uptimePercent: 100 and empty events arrays.

Error responses

Status	When
`400`	Missing/invalid query, both or neither of `dashboardId`/`componentId`, invalid timezone, or future month
`403`	Non-admin role, missing `uptimeReports` capability, or authentication failure
`404`	Dashboard not found (dashboard scope) or component not found (component scope)
`500`	Unexpected server error