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
Parameters
This route takes no parameters.
Responses
| Status | Body | Description |
|---|---|---|
200 | Health (application/json) | OK |
503 | Health (application/json) | The database is down. |
default | Problem (application/problem+json) | Any other error (405, 500, 504). |
Response body
A 200 carries a 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
curl -sS 'https://api.secblast.com/v3/health'Open this route in the console
More in Coverage, usage and service
Previous: GET /v3/forms · Next: GET /v3/openapi.json
Markdown version: /docs/reference/get-health.md