# Coverage certificates

A coverage certificate records one source on one UTC day. It shows whether PIT holds data for that day, the number of parsed rows, and the forms counted. Every cut returns the certificates it read.

Reference page. Updated 2026-08-26 against the corpus described on [coverage](https://pit.aqx.llc/docs/coverage).

## 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.

**GET /v1/coverage?source=sec.edgar&date=2023-03-10 — complete**

```
{
  "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`.

**data/raw/sec/2023-03/2023-03-10/master.idx — line 4,543 of 5,461**

```
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.

|  | Complete and empty | Gap |
| --- | --- | --- |
| HTTP | 200 | 409 |
| `status` | `ok` | `coverage_missing` |
| `count` | `0` | JSON `null` |
| `results` | `[]` | `[]` |
| `error` | `null` | `coverage_missing` |
| Read it as | We hold that day and nothing matched the cut. | We do not hold that day, so the number of filings is unknown. |

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.

| Shape | Example | Names |
| --- | --- | --- |
| Partition | `sec.edgar/2023-03-10` | One source on one UTC day. |
| Identity | `identity.ticker/FB@2023-03-10` | One ticker's identity on one UTC day. |
| Frontier | `sec.edgar/frontier:2008-09-01..2023-03-31;holes=93` | Where a source's certified span starts and stops, with the count of days inside it that are not complete at or before the cut. |
| Availability | `availability.sec.edgar/2023-03-10` | A source asked for `available_at` that holds no availability evidence. |

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):

- **No certificate**: No source in scope contains any certificates. For example, a misspelled `source`.
- **Partition**: The cut's UTC day is not `complete` for a source in scope. This includes missing certificates, partial certificates, and dates outside the certified range.
- **Identity**: A `ticker` has no point-in-time mapping interval valid at `as_of`.
- **Availability**: The request sets `visible_by=available_at` on a source without availability metadata.

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.

**GET /v1/news?ticker=FB&as_of=2023-03-10T23:59:59Z — 409 · coverage_missing**

```
{
  "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](https://pit.aqx.llc/glossary/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](https://pit.aqx.llc/docs/mapping) 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](https://pit.aqx.llc/legal/license).

- **587,689** queryable rows
- **7** sources
- **606** certificates
- **2023-03-31** last SEC partition

| `source_id` | Lane | Rows | Complete | Missing | First | Last |
| --- | --- | --- | --- | --- | --- | --- |
| `sec.edgar` | `certified_pit` | 563,594 | 204 | 99 | 2008-09-01 | 2023-03-31 |
| `us.federal_register.pi` | `certified_pit` | 21,736 | 182 | 91 | 2020-02-01 | 2023-03-31 |
| `us.cftc.cot` | `certified_pit` | 1,149 | 4 | 0 | 2023-03-07 | 2023-03-28 |
| `us.ofac.sdn` | `certified_pit` | 7 | 4 | 1 | 2023-03-09 | 2024-08-06 |
| `us.fda.enforcement.drug` | `forward_first_seen` | 85 | 7 | 0 | 2023-03-06 | 2023-03-12 |
| `us.fda.enforcement.device` | `forward_first_seen` | 41 | 7 | 0 | 2023-03-06 | 2023-03-12 |
| `us.fda.enforcement.food` | `forward_first_seen` | 17 | 7 | 0 | 2023-03-06 | 2023-03-12 |

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.

> **SEC coverage spans ten separate months:** 2008-09, 2020-02, 2020-03, 2021-01, 2021-10, and 2022-11 through 2023-03. Only the last period is continuous: 151 calendar days from 2022-11-01 to 2023-03-31. Every day is certified, with 103 complete and 48 missing. Federal Register public inspection covers the same window. Outside this window, the newest backfilled row is one OFAC action dated 2024-08-06. Rows dated after 2026-08-26 come from the live tape rather than certified backfill.

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.

**GET /v1/coverage?source=sec.edgar&date=2023-03-11 — missing**

```
{
  "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).