# GET /v3/health

Liveness: one database round trip, the document root, and whether the snapshot store is usable. 200 unless the database is down.

**API key:** not needed.

**Group:** [Coverage, usage and service](https://www.secblast.com/docs/reference#coverage-usage-and-service)

## Parameters

This route takes no parameters.

## Responses

| Status | Body | Description |
|---|---|---|
| `200` | [Health](https://www.secblast.com/docs/reference/schemas#schema-health) (`application/json`) | OK |
| `503` | [Health](https://www.secblast.com/docs/reference/schemas#schema-health) (`application/json`) | The database is down. |
| `default` | [Problem](https://www.secblast.com/docs/reference/schemas#schema-problem) (`application/problem+json`) | Any other error (405, 500, 504). |

## Response body

A `200` carries a [Health](https://www.secblast.com/docs/reference/schemas#schema-health) object.

| Field | Type | Required | Description |
|---|---|---|---|
| `checks` | object | yes |   |
| `checks.callbacks` | string | no | Webhook delivery, judged per organization: the lateness of the least late organization among those with a first attempt due or one made in the last minute (one organization's own backlog does not count while others are served on time). ok: at most 60 s past due. degraded: up to 5 minutes. down: more, or the delivery table cannot be read (also while the database is down). degraded and down make the status degraded at any hour, never an outage. disabled: this deployment has no webhook delivery. One of: `ok`, `degraded`, `down`, `disabled`. |
| `checks.db` | string | no | One of: `ok`, `fail`. |
| `checks.docs_root` | string | no | One of: `ok`, `missing`. |
| `checks.live` | string | no | Live ingest (the daemon that registers filings seconds after SEC accepts them). ok: its heartbeat is at most 45 s old and it is polling, idle outside the window, or catching up. paused: SEC refused a request; nothing is sent until live.paused_until, and the 30 careful minutes after. degraded: SEC unreachable, database down, disk low, or halted after repeated pauses. down: no heartbeat (not running, stopping, or its status could not be read). disabled: this deployment has no live ingest. One of: `ok`, `paused`, `degraded`, `down`, `disabled`. |
| `checks.mcp` | string | no | The MCP server sb_mcp_v3 (its /healthz, probed at most every 5 s). disabled: this deployment does not name one. Informational: it never changes status. One of: `ok`, `down`, `disabled`. |
| `checks.store` | string | no | The snapshot store. stale: its snapshot is more than 3 days old (still used). loading: no snapshot served yet. disabled: not configured. One of: `ok`, `stale`, `loading`, `unavailable`, `disabled`. |
| `checks.stream` | string | no | The filing stream (the sequencer that writes the log behind /v3/stream). ok: it wrote its cursor at most 30 s ago. stale: the cursor is older, or there is none; the status is then degraded, never an outage. stale also when the database cannot be read. disabled: this deployment has no stream. One of: `ok`, `stale`, `disabled`. |
| `live` | object | no | Present only when live ingest is enabled. Counts and the full heartbeat are on /v3/coverage, which needs a key. |
| `live.lag_seconds` | integer \| null | no | Median seconds from SEC's acceptance to the filing being seen, over the last 15 minutes; null with fewer than 5 filings, and when the figure is negative or absurd. |
| `live.last_new_filing_at` | date-time (RFC 3339, UTC) \| null | no | When the newest filing was first seen. |
| `live.last_poll_at` | date-time (RFC 3339, UTC) \| null | no | The last successful poll of SEC's list of new filings. |
| `live.paused_until` | date-time (RFC 3339, UTC) \| null | no | End of a pause in force; null otherwise. |
| `live.state` | string \| null | no | The daemon's own state in its last heartbeat (ok, idle, catching_up, paused, cautious, sec_unreachable, db_down, disk_low, halted, stopping, stopped, failed), or dry_run when the daemon that answers is a dry run (it registers no filings; checks.live is then never ok); null without a heartbeat or when it is none of these. It is the daemon's last word, so a daemon that died still shows its last state: checks.live is the judgement, which also knows how old the heartbeat is and whether the session ended. |
| `metering` | object | no | Only when the API runs with a metering switches file (one in force, or one that was refused): the mode of each feature; config (ok \| refused: the file cannot be read or is invalid, and the previous switches, or all off, stay), config_error and config_last_good (when a valid file was last taken); the usage flusher (last success, pending records, failures, events written and dropped, whether the month was read back); the age of the cached entitlements; entitlements_statement (unchecked \| ok \| insufficient_privilege \| failed: whether this role can run the entitlements statement, which reads v3_acct_entitlements and v3_usage_rollup_state; updated by every entitlements read, and checked actively while a feature is enforced) and entitlements_error; limits_unknown (requests served without limits because their org's limits could not be read); and the refusal counters. It makes status degraded, never an outage, while the file is refused, or while a feature is enforced and entitlements_statement is insufficient_privilege. |
| `status` | string | yes | degraded unless every check is ok and the metering block (when present) is not degraded (a store that is not configured does not degrade; live ingest counts only when it is enabled, and only on a weekday between 06:00 and 22:00 New York time, when SEC accepts filings; the filing stream and webhook delivery count only when enabled, at any hour). The HTTP status is 503 only when the database is down. One of: `ok`, `degraded`. |
| `store` | object | no | The snapshot in use. Counts and load details are on /v3/coverage, which needs a key. |
| `store.available` | boolean | no |   |
| `store.snapshot_date` | date (YYYY-MM-DD) \| null | no |   |
| `store.stale` | boolean \| null | no |   |
| `time` | date-time (RFC 3339, UTC) | no |   |
| `version` | string | no |   |

## Example request

```bash
curl -sS 'https://api.secblast.com/v3/health'
```

[Open this route in the console](https://www.secblast.com/console#get-v3-health)

## More in Coverage, usage and service

Previous: [`GET /v3/forms`](https://www.secblast.com/docs/reference/get-forms) · Next: [`GET /v3/openapi.json`](https://www.secblast.com/docs/reference/get-openapi-json)
