# Uptime

> For AI agents: the full docs index is at https://brixsignage.com/llms.txt, and every page has a markdown twin (add .md to the path).

Base URL `https://api.brixsignage.com`. Send `Authorization: Bearer $BRIX_API_KEY` unless an operation says Auth: none or Auth: no API key. The Permission line names what the key must hold. See [Authentication and scopes](https://brixsignage.com/developers/authentication.md), [Errors and rate limits](https://brixsignage.com/developers/errors-and-rate-limits.md) and [Pagination](https://brixsignage.com/developers/pagination.md).

- [GET /v1/uptime](#get-v1-uptime)

Every 4xx and 5xx response below returns this body:

| Field | Type | Description |
| --- | --- | --- |
| `error` | string | Machine-readable code: `unauthorized`, `forbidden`, `not_found`, `validation_error`, `conflict`, `rate_limited`, `internal_error`, … |
| `message` | string | Human-readable explanation. Safe to show an operator. |
| `requestId` | string | Present on 5xx: quote it to support. |

## GET /v1/uptime

Get uptime report

Get an uptime report for a date range, with online percentage per screen and per location, downtime windows, and mean time to recovery.

**Notes.**
- Only screens at locations the caller can see. `outageSummary` is present only when there were outages.

Auth: Bearer token. Permission: `screen.view`.

Parameters:

| Name | In | Type | Required | Description |
| --- | --- | --- | --- | --- |
| `from` | query | string | no | ISO-8601 start (default: the start of the workspace's offline-history window). |
| `to` | query | string | no | ISO-8601 end (default: now). |
| `screenId` | query | string | no | Only this screen. |

```bash
curl "https://api.brixsignage.com/v1/uptime" \
  -H "Authorization: Bearer $BRIX_API_KEY"
```

Response 200: Success.

| Field | Type | Description |
| --- | --- | --- |
| `data` | object |  |
| `data.from` | string \| null |  |
| `data.to` | string \| null |  |
| `data.offlineRetentionDays` | integer | How far back offline history is kept. |
| `data.fleet` | object |  |
| `data.fleet.screenCount` | integer |  |
| `data.fleet.onlinePct` | number | 0–100. |
| `data.fleet.outages` | integer |  |
| `data.fleet.mttrSec` | number \| null | Mean time to recover, in seconds; null with no recovered outage. |
| `data.fleet.totalDowntimeSec` | number |  |
| `data.fleet.plannedDarkSec` | number | Downtime the screen was expected to be dark (a schedule or power policy). |
| `data.fleet.plannedDarkOutages` | integer |  |
| `data.fleet.outageSummary` | OutageSummary | Outages in a window, by cause. |
| `data.fleet.outageSummary.windowDays` | integer |  |
| `data.fleet.outageSummary.count` | integer | Unplanned outages in the window. |
| `data.fleet.outageSummary.byCause` | object | Outage count per cause; a cause with none is absent. |
| `data.fleet.outageSummary.byBucket` | object |  |
| `data.fleet.outageSummary.topCause` | string \| null |  |
| `data.fleet.outageSummary.topCauseShare` | number |  |
| `data.fleet.outageSummary.hedgedShare` | number |  |
| `data.fleet.outageSummary.lastCause` | object \| null |  |
| `data.fleet.outageSummary.lastAt` | string \| null |  |
| `data.fleet.outageSummary.lastKnownCause` | object \| null |  |
| `data.fleet.outageSummary.avgRssiDbm` | number \| null |  |
| `data.fleet.outageSummary.insight` | string \| null | The rollup sentence, e.g. `All 6 were Wi-Fi drops.` |
| `data.fleet.screensWithOutages` | integer |  |
| `data.screens` | array of object |  |
| `data.screens[].screenId` | string |  |
| `data.screens[].screenName` | string |  |
| `data.screens[].nodeId` | string \| null |  |
| `data.screens[].locationLabel` | string \| null |  |
| `data.screens[].status` | "online" \| "offline" \| "pairing" |  |
| `data.screens[].lastSeenAt` | string \| null |  |
| `data.screens[].windowSec` | number |  |
| `data.screens[].downtimeSec` | number |  |
| `data.screens[].uptimeSec` | number |  |
| `data.screens[].onlinePct` | number |  |
| `data.screens[].outages` | integer |  |
| `data.screens[].mttrSec` | number \| null |  |
| `data.screens[].plannedDarkOutages` | integer |  |
| `data.screens[].plannedDarkSec` | number |  |
| `data.screens[].downtimeWindows` | array of object |  |
| `data.screens[].downtimeWindows[].from` | string | ISO-8601 timestamp (UTC). |
| `data.screens[].downtimeWindows[].to` | string \| null | Null while the screen is still down. |
| `data.screens[].downtimeWindows[].durationSec` | number |  |
| `data.screens[].downtimeWindows[].detectionPath` | string | How the outage was noticed, e.g. `ws-close`, `heartbeat-timeout`. |
| `data.screens[].downtimeWindows[].cause` | string \| null |  |
| `data.screens[].downtimeWindows[].causeDetail` | string \| null |  |
| `data.screens[].downtimeWindows[].causeLabel` | string \| null |  |
| `data.screens[].downtimeWindows[].reason` | string \| null |  |
| `data.screens[].downtimeWindows[].expectedDark` | boolean \| null |  |
| `data.screens[].downtimeWindows[].expectedReason` | string \| null |  |
| `data.screens[].outageSummary` | OutageSummary | Outages in a window, by cause. |
| `data.screens[].outageSummary.windowDays` | integer |  |
| `data.screens[].outageSummary.count` | integer | Unplanned outages in the window. |
| `data.screens[].outageSummary.byCause` | object | Outage count per cause; a cause with none is absent. |
| `data.screens[].outageSummary.byBucket` | object |  |
| `data.screens[].outageSummary.topCause` | string \| null |  |
| `data.screens[].outageSummary.topCauseShare` | number |  |
| `data.screens[].outageSummary.hedgedShare` | number |  |
| `data.screens[].outageSummary.lastCause` | object \| null |  |
| `data.screens[].outageSummary.lastAt` | string \| null |  |
| `data.screens[].outageSummary.lastKnownCause` | object \| null |  |
| `data.screens[].outageSummary.avgRssiDbm` | number \| null |  |
| `data.screens[].outageSummary.insight` | string \| null | The rollup sentence, e.g. `All 6 were Wi-Fi drops.` |
| `data.locations` | array of object |  |
| `data.locations[].nodeId` | string \| null |  |
| `data.locations[].name` | string |  |
| `data.locations[].screenCount` | integer |  |
| `data.locations[].onlinePct` | number |  |
| `data.locations[].windowSec` | number |  |
| `data.locations[].downtimeSec` | number |  |
| `data.locations[].outages` | integer |  |
| `data.locations[].mttrSec` | number \| null |  |
| `data.locations[].outageSummary` | OutageSummary | Outages in a window, by cause. |
| `data.locations[].outageSummary.windowDays` | integer |  |
| `data.locations[].outageSummary.count` | integer | Unplanned outages in the window. |
| `data.locations[].outageSummary.byCause` | object | Outage count per cause; a cause with none is absent. |
| `data.locations[].outageSummary.byBucket` | object |  |
| `data.locations[].outageSummary.topCause` | string \| null |  |
| `data.locations[].outageSummary.topCauseShare` | number |  |
| `data.locations[].outageSummary.hedgedShare` | number |  |
| `data.locations[].outageSummary.lastCause` | object \| null |  |
| `data.locations[].outageSummary.lastAt` | string \| null |  |
| `data.locations[].outageSummary.lastKnownCause` | object \| null |  |
| `data.locations[].outageSummary.avgRssiDbm` | number \| null |  |
| `data.locations[].outageSummary.insight` | string \| null | The rollup sentence, e.g. `All 6 were Wi-Fi drops.` |
| `data.locations[].screensWithOutages` | integer |  |

Response 401: Missing, expired or revoked bearer token.

Response 403: The token lacks the permission this operation needs (see `x-brix-permission`).

Response 422: `from` or `to` is not an ISO-8601 timestamp.

Response 5XX: Server error. The body carries a `requestId` to quote to support.
