# Get uptime report

Compute a monthly uptime report for a status dashboard or org component (admin + uptimeReports feature).

Source: https://statusdashboard.com/docs/api/reports/uptime/get

`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](/docs/api) 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**

```bash
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)

```bash
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`**

```json
{
  "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                                                                                  |