Skip to content

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

StatusBodyDescription
200Health (application/json)OK
503Health (application/json)The database is down.
defaultProblem (application/problem+json)Any other error (405, 500, 504).

Response body

A 200 carries a Health object.

FieldTypeRequiredDescription
checksobjectyes
checks.callbacksstringnoWebhook 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.dbstringnoOne of: ok, fail.
checks.docs_rootstringnoOne of: ok, missing.
checks.livestringnoLive 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.mcpstringnoThe 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.storestringnoThe 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.streamstringnoThe 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.
liveobjectnoPresent only when live ingest is enabled. Counts and the full heartbeat are on /v3/coverage, which needs a key.
live.lag_secondsinteger | nullnoMedian 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_atdate-time (RFC 3339, UTC) | nullnoWhen the newest filing was first seen.
live.last_poll_atdate-time (RFC 3339, UTC) | nullnoThe last successful poll of SEC's list of new filings.
live.paused_untildate-time (RFC 3339, UTC) | nullnoEnd of a pause in force; null otherwise.
live.statestring | nullnoThe 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.
meteringobjectnoOnly 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.
statusstringyesdegraded 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.
storeobjectnoThe snapshot in use. Counts and load details are on /v3/coverage, which needs a key.
store.availablebooleanno
store.snapshot_datedate (YYYY-MM-DD) | nullno
store.staleboolean | nullno
timedate-time (RFC 3339, UTC)no
versionstringno

Example request

Shell
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