Coverage certificates

The certificate

Each certificate covers one source on one UTC day. status is complete, missing, or partial. A complete certificate contains the row count PIT holds. A missing certificate contains row_count: null instead of 0.

{
  "source_id": "sec.edgar",
  "partition_date": "2023-03-10",
  "status": "complete",
  "row_count": 3124,
  "scope": {
    "scope_id": "sec.edgar.forms.v1",
    "selection": "form_allowlist",
    "forms": ["10-K", "10-K/A", "10-Q", "10-Q/A", "13D", "13D/A", "13G",
              "13G/A", "4", "4/A", "6-K", "6-K/A", "8-K", "8-K/A",
              "SC 13D", "SC 13D/A", "SC 13G", "SC 13G/A"],
    "scope_sha256": "d17340d6…85e5e2af"
  }
}

scope defines what the count measures. For sec.edgar, this is an allowlist of 18 form types. scope_sha256 is a SHA-256 hash of that list to verify if two certificates use the same form types. For example, the certificate above counts 3,124 rows from an EDGAR daily index containing 5,461 rows. The remaining 2,337 rows cover 129 form types outside the allowlist, as declared in scope.

CIK|Company Name|Form Type|Date Filed|File Name
719739|SVB FINANCIAL GROUP|8-K|20230310|edgar/data/719739/0001193125-23-067777.txt

Certified rows are parsed from index files. Each fetched index file is stored alongside a master.idx.receipt.json file containing the source URL, byte count, fetch timestamp, and file SHA-256 hash.

master.idx sha256
b5ed4c89350f922466a6e31e9831c8c29c3881e24b87a06f19b742951e628732

Empty days and gaps

A cut over a certified day may return zero rows. A cut over an unmined day has no data. These two cases return different HTTP status codes.

A complete certificate can also have row_count: 0 if the publisher published no in-scope records that day. For example, us.fda.enforcement.drug contains seven certified days: six are complete with 0 rows, and one contains all 85 rows.

Coverage keys

coverage.touched and coverage.missing contain keys rather than full certificates. Each key identifies an underlying dependency. There are four key formats.

Source IDs and tickers cannot contain /, so the four key formats never collide. holes counts missing days at or before the cut date. The example above is a cut at 2023-03-10, while the same key at 2023-03-31 returns holes=99. Call /v1/coverage to list the missing days.

What turns a cut into a 409

Keys in touched define the query scope. Keys in missing prevent the query from running: status becomes coverage_missing, count returns JSON null, and no rows are read. Four conditions add a key to missing (where as_of is the requested timestamp):

Missing dates before the cut date do not cause a 409 error. The API only checks coverage for the cut's UTC day. Earlier gaps are counted in the frontier key's holes field. Call /v1/coverage to list those dates.

Setting source narrows query scope. A cut without a source checks all seven sources. On 2023-03-10, two sources (us.cftc.cot and us.ofac.sdn) have no certificate for that day. An unscoped call returns 409, while adding source=sec.edgar returns 200.

Identity gaps

An identity key in missing means no point-in-time interval covers that ticker at as_of. This happens when PIT never curated the ticker, the interval expired, or the ticker was reassigned to another registrant.

{
  "status": "coverage_missing",
  "count": null,
  "results": [],
  "coverage": {
    "touched": ["identity.ticker/FB@2023-03-10", "sec.edgar/2023-03-10", …],
    "missing": ["identity.ticker/FB@2023-03-10", …]
  }
}

For example, FB became META on 2022-06-09. No interval maps FB to March 2023. The SEC partition for that day is complete, but the identity check fails. Use ticker=META for cuts after the rename, and ticker=FB for cuts before it.

A query specifying a ticker records its identity key in touched whether or not the ticker resolves. A ticker whose only interval comes from today's ticker file also counts as a gap. That file records current ownership, not ownership at as_of. See lookahead bias.

Two cases look similar but are not gaps. First, identity resolves but matches no rows (count: 0, status: ok). Second, a ticker and cik pair have no overlap: identity is valid at the cut date, but does not match that CIK. See identity for mapping intervals.

What the corpus holds

Data retrieved from /v1/meta on 2026-08-26. The lane column shows how a row received its timestamp: certified_pit from a stored publisher document, or forward_first_seen from poller discovery time. Source licenses are on the license page.

First and last dates are partition_date bounds assigned by the publisher. They are not published_at bounds. On sec.edgar, some index rows list a Date Filed earlier than their partition date.

Of the 99 SEC days marked missing, 88 are Saturdays and Sundays, and 11 are US federal holidays. Every calendar day within these ten months has a certificate. Federal Register public inspection has 91 such days. They appear as missing because PIT did not fetch index files for them, leaving no data to certify.

Calling /v1/coverage

GET /v1/coverage takes a key and three optional parameters: source, date formatted as YYYY-MM-DD, and as_of. Querying an uningested source and date returns a missing certificate instead of a 404 status.

{
  "source_id": "sec.edgar",
  "partition_date": "2023-03-11",
  "status": "missing",
  "row_count": null
}

The public route /v1/sample/coverage returns the 16 sample certificates without requiring an API key. This includes sec.edgar/2023-03-09 (2,828 rows) and sec.edgar/2023-03-10 (3,124 rows).