GET /v3/coverage
Ingest coverage: per feed day the latest non-superseded ingest run and the newest complete reconcile run, overall totals, and the snapshot store. Without from and to the last 90 feed days are listed, leaving out a day whose latest run is source_invalid and that is older than the oldest feed day with filings (a trial run outside the covered days; an explicit window lists it, and such a day inside or after the covered days is always listed); with either, the newest 366 feed days of that window at most (truncated says when days were left out, window what was used). The totals and the default window (neither from nor to) are computed in the background, never by a request: once at start and then every few minutes (5 by default; less often when a computation is slow). Each says when it was computed (computed_at, totals.computed_at) and is served until the next computation replaces it. Until the first computation after a start has finished the answer is 503 with code warming_up and Retry-After. An explicit window is computed by its request, at most once a minute per window.
API key: required. See Authentication.
Group: Coverage, usage and service
Parameters
| Name | In | Type | Required | Default | Description |
|---|---|---|---|---|---|
from | query | date (YYYY-MM-DD) | no | First feed day (inclusive), YYYY-MM-DD. Default: see the description. | |
to | query | date (YYYY-MM-DD) | no | Last feed day (inclusive), YYYY-MM-DD. |
Responses
| Status | Body | Description |
|---|---|---|
200 | Coverage (application/json) | OK |
400 | Problem (application/problem+json) | Invalid or unknown parameter. |
401 | Problem (application/problem+json) | Missing, invalid or inactive API key (code unauthorized), or a refused access token (code invalid_token: malformed, unknown key, bad signature, expired, wrong issuer or audience, revoked grant). WWW-Authenticate names the protected-resource metadata (RFC 9728). |
503 | Problem (application/problem+json) | Database unavailable (code db_unavailable); or the answer, which the server computes in the background, has not been computed yet since it started (code warming_up). Retry the same request after the Retry-After delay. |
default | Problem (application/problem+json) | Any other error (405, 500, 504). |
Response body
A 200 carries a Coverage object.
| Field | Type | Required | Description |
|---|---|---|---|
computed_at | date-time (RFC 3339, UTC) | no | When data (the per-day part) was computed, UTC. The value is served until a later computation replaces it. |
data | array of CoverageDay | yes | Per feed day, the latest non-superseded ingest run; newest day first. At most window.max_days days: the newest ones of the window. The default window is recomputed in the background every few minutes, an explicit one by a request at most once a minute; computed_at says when. |
live | object | null | no | Live ingest: the daemon's last heartbeat (it writes one every 10 s). Null when there is none or live ingest is not enabled. It can be old: live_check says what to make of it. Only the members listed here are given, each checked: a number outside 0..10^15, a time that is not one, or a word outside its list is null, and no free text of the daemon is passed on. |
live.covered_until | date-time (RFC 3339, UTC) | null | no | SEC's list of new filings has been read without a gap up to here. |
live.ended | string | null | no | How the session ended; null while it runs. The reason is in the daemon's log, not here. One of: clean, failed, null. |
live.fetch | object | no | requests, http_404, http_429, http_5xx, network, integrity, too_large, bytes, and recent {requests, failed}. |
live.filings | object | no | Counts since the session started: seen, listed, documents, failed, skipped_known, and per_min_1, per_min_5, per_min_peak. |
live.heartbeat_at | date-time (RFC 3339, UTC) | null | no | |
live.items_unmapped | number | null | no | 8-K item descriptions seen without an item code. |
live.last_new_accession | string | null | no | |
live.last_new_filing_at | date-time (RFC 3339, UTC) | null | no | |
live.latency_ms | object | no | recent (the last window_s seconds) and day: n, and p50 / p95 of accept_to_seen, seen_to_listed, seen_to_documents. |
live.limiter | object | no | The shared SEC request limiter as the daemon sees it: priority (on, off, unavailable), wait_ms {p50, p95}, waits_over_1s, refused. |
live.mode | string | null | no | One of: live, dry_run, null. |
live.paused_until | date-time (RFC 3339, UTC) | null | no | |
live.pauses_24h | number | null | no | |
live.poll | object | no | Counts of polls and sweeps of SEC's list; rtt_ms and skew_ms in milliseconds. |
live.poll.below_page0 | number | null | no | |
live.poll.failed | number | null | no | |
live.poll.last_ok_at | date-time (RFC 3339, UTC) | null | no | |
live.poll.last_poll_failed | boolean | no | Whether the last poll failed. The error text stays in the daemon's log. |
live.poll.ok | number | null | no | |
live.poll.out_of_order | number | null | no | |
live.poll.overflows | number | null | no | |
live.poll.pages_swept | number | null | no | |
live.poll.rtt_ms | object | no | |
live.poll.skew_ms | number | null | no | |
live.poll.sweeps | object | no | |
live.poll.sweeps_abandoned | number | null | no | |
live.poll.sweeps_exhausted | number | null | no | |
live.poll.uncovered | array of object | no | Spans of SEC's list a sweep could not cover (the nightly feed covers those filings); at most 50. |
live.poll.uncovered[].at | date-time (RFC 3339, UTC) | null | no | |
live.poll.uncovered[].from | date-time (RFC 3339, UTC) | null | no | |
live.poll.uncovered[].reason | string | null | no | One of: max_start, page_unanswered, null. |
live.poll.uncovered[].until | date-time (RFC 3339, UTC) | null | no | |
live.poll_interval_ms | number | null | no | |
live.queue | object | no | fetch_fresh, fetch_backlog, build, retry, oldest_age_s, behind_since. |
live.roles_unmapped | integer | no | Role strings of SEC's list that have no v3 role (how many, not which). |
live.schema | number | null | no | |
live.started_at | date-time (RFC 3339, UTC) | null | no | |
live.state | string | null | no | One of: ok, idle, catching_up, paused, cautious, sec_unreachable, db_down, disk_low, halted, stopping, stopped, failed, null. |
live.window_open | boolean | null | no | |
live_check | string | no | As checks.live of /v3/health. One of: ok, paused, degraded, down, disabled. |
snapshot | object | yes | The snapshot store and the snapshot it serves. |
snapshot.accessions | integer | null | no | Distinct filings in the snapshot. |
snapshot.age_days | integer | null | no | |
snapshot.available | boolean | no | |
snapshot.date | date (YYYY-MM-DD) | null | no | |
snapshot.fallback | boolean | null | no | A newer snapshot exists but could not be loaded. |
snapshot.filers | integer | null | no | |
snapshot.filings | integer | null | no | Filing listings in the snapshot (a filing listed by two filers counts twice). |
snapshot.loaded_at | date-time (RFC 3339, UTC) | null | no | |
snapshot.reloading | boolean | null | no | A newer snapshot is being loaded; the current one keeps serving. |
snapshot.stale | boolean | null | no | The snapshot is more than 3 days old. |
snapshot.state | string | no | One of: ok, stale, loading, unavailable, disabled. |
snapshot.tickers_date | date (YYYY-MM-DD) | null | no | Newest copy of SEC's ticker file. |
snapshot.tickers_from | date (YYYY-MM-DD) | null | no | Oldest copy kept. |
totals | object | yes | Table-wide totals, whatever the window; recomputed in the background every few minutes (5 by default). They are served until a later computation replaces them: when one fails, the previous totals stay, and computed_at shows their age. |
totals.accepted_at_stored | integer | no | Filings with an acceptance time stored in v3 (any source: a header time, or SEC's from the snapshot sync). |
totals.amendments | integer | no | Amendments, deleted ones excluded. |
totals.amendments_resolved | integer | no | Of those amendments, the ones linked to their original. |
totals.computed_at | date-time (RFC 3339, UTC) | no | When the totals were computed, UTC. |
totals.deleted_filings | integer | no | |
totals.documents | integer | no | |
totals.filings | integer | no | |
totals.max_feed_date | date (YYYY-MM-DD) | null | no | |
totals.max_filing_date | date (YYYY-MM-DD) | null | no | |
totals.min_feed_date | date (YYYY-MM-DD) | null | no | |
totals.min_filing_date | date (YYYY-MM-DD) | null | no | |
truncated | boolean | yes | True when the window holds more feed days than max_days: the older ones are left out. Ask for them with from / to. |
window | object | yes | The window of feed days this answer covers. |
window.default | boolean | no | True when neither from nor to was given: the last 90 feed days. |
window.from | date (YYYY-MM-DD) | null | no | The from that was asked for; without one, the oldest day listed (null when no day is listed). |
window.max_days | integer | no | The most days one answer lists: 90 for the default window, 366 when from or to is given. |
window.to | date (YYYY-MM-DD) | null | no | The to that was asked for; without one, the newest day listed (null when no day is listed). |
Example request
curl -sS -H "Authorization: Bearer $SECBLAST_API_KEY" \
'https://api.secblast.com/v3/coverage'Open this route in the console
More in Coverage, usage and service
Next: GET /v3/coverage/count
Markdown version: /docs/reference/get-coverage.md