GET /outages/buildings

Who this is for. This endpoint feeds a provider’s NOC dashboard or a monitoring integration — “which of my buildings are down right now, and how flaky has this one been this week.” It is deliberately not an incident feed: there is no cause, no operator notes, no estimated restore time, no switch/interface identity, and no subscriber/affected counts. A provider reads where, never how or whose. These fields are absent on purpose, not omitted by oversight.

Endpoint

GET /partner/outages/buildings

Auth: X-API-Key: krnl_... with the provisioning:read scope. A key scoped provisioning:write also passes — write implies read.

Scope of the answer

Every live building in your coverage footprint is reported, whether or not you have subscribers there — this is a coverage-scoped read, not a subscription-scoped one. A building your account covers but currently has no customers in still shows up. Buildings still in planning, provisioning or testing are not listed — only buildings whose pipeline status is live are included. Only building-level and NOC-level outages are reflected. A single-line (per-customer loop) fault never appears here, however long it has been open. An empty buildings array with next_cursor: null means you have no live covered buildings right now — not that something failed. If that is unexpected, coverage has not been configured for your provider yet.

Query parameters

Parameter	Type	Default	Notes
`status`	`outage` \| `ok`	(omitted)	Filter to one status. Omit to get every building regardless of status.
`limit`	integer, 1–1000	`500`	Page size, applied after any `status` filter.
`cursor`	string	(none)	Opaque. Pass the `next_cursor` value from the previous page verbatim; do not construct or parse it yourself.

Results are sorted by building_id ascending. That fixed order is what makes cursor stable and resumable — paging through does not skip or repeat a building relative to where you left off. An out-of-range limit or an unrecognized status value returns 422.

Response — 200 OK

{
  "window_days": 7,
  "generated_at": "2026-09-18T14:32:07.911203+00:00",
  "buildings": [
    {
      "building_id": "3a0f1c2e-...",
      "address": "12 Wharf St",
      "city": "Victoria",
      "province": "BC",
      "postal_code": "V8V 1A1",
      "status": "outage",
      "since": "2026-09-18T09:14:02+00:00",
      "recent": {
        "count": 3,
        "last_cleared_at": "2026-09-15T22:40:11+00:00"
      }
    },
    {
      "building_id": "8b41d9aa-...",
      "address": "44 Fort St",
      "city": "Victoria",
      "province": "BC",
      "postal_code": "V8V 1B2",
      "status": "ok",
      "since": null,
      "recent": {
        "count": 0,
        "last_cleared_at": null
      }
    }
  ],
  "next_cursor": null
}

Field	Meaning
`window_days`	The size of the rolling window `recent` summarizes — currently `7`.
`generated_at`	ISO 8601 UTC timestamp of when the status was computed, not when this response was sent. Because results are cached per provider for 15 seconds, it may be up to 15 seconds old. An unchanged `generated_at` between two calls means you were served the same cached result.
`buildings[].status`	`outage` if the building has a currently open outage event, otherwise `ok`.
`buildings[].since`	The `detected_at` of the earliest still-open event for this building, ISO 8601. `null` when `status` is `ok`.
`buildings[].recent.count`	Rolling 7-day count: events detected in the last `window_days` days, plus any event that is still open regardless of how old it is — an outage open for a month still counts every time you ask.
`buildings[].recent.last_cleared_at`	The most recent `resolved_at` among events detected within the window, ISO 8601, or `null` if none cleared in the window.
`next_cursor`	Present only when more rows exist past this page (i.e. more results matched your `status` filter than `limit`). Pass it back as `cursor` to get the next page; `null` means you have the whole (filtered) result set.

Polling

Poll no faster than every 15 seconds. The status fold behind this endpoint is cached per provider for 15 s; a tighter loop just replays the same cached result against your own rate-limit budget — which is exactly what an unchanged generated_at between two calls tells you. Polling faster than every 15 seconds gains nothing.

Errors

Status	Detail
401	Missing or invalid `X-API-Key`
403	API access disabled for your account, or the key is missing the `provisioning:read` scope
422	`status` is neither `outage` nor `ok`, or `limit` is outside 1–1000
429	Rate limit exceeded — 60 requests / minute per API key
503	Outage status is temporarily unavailable

Treat 503 as unknown, never as all-clear. The endpoint never degrades to an empty or all-ok 200 on an internal failure — an empty list would read as “your whole footprint is fine,” which is exactly the false signal this surface is built to avoid. A 503 means the fold could not be computed; retry rather than assuming nothing is wrong.

Overview

Plan Discovery

Provisioning

Reports

Checkout Utilities

Subscribers & Subscriptions

AI Support Agent

Provider Operations (Internal API)

Endpoint

Scope of the answer

Query parameters

Response — 200 OK

Polling

Errors

​Endpoint

​Scope of the answer

​Query parameters

​Response — 200 OK

​Polling

​Errors

Endpoint

Scope of the answer

Query parameters

Response — 200 OK

Polling

Errors