# As-of queries

An as-of query returns rows where a visibility clock is at or before a specified timestamp. Set the timestamp with `as_of`. The comparison is inclusive and uses UTC. Choose the clock with `visible_by`.

Updated 2026-08-26. Corpus figures come from a running server.

## Choosing the clock

`visible_by` accepts `published_at`, `available_at`, or `committed_at`. If empty or omitted, it defaults to `published_at`, which is the v1 index-replay default. The row fields `event_at` and `acceptance_at` are not accepted as clocks. Passing either field returns `invalid_clock`.

| Clock | What it records | What an as-of cut on it answers |
| --- | --- | --- |
| `published_at` | The filer, publisher or index clock. | What the index carried by T. On SEC rows the daily index gives a date and no time, so the value sits at 23:59:59Z on that date. |
| `available_at` | First evidenced public availability, with `availability_basis` saying whether the evidence is a receipt or a schedule. | What was demonstrably public by T. The field is null on all 563,594 SEC rows in this corpus, and a cut on it returns 409 for those days. |
| `committed_at` | When the row was written to our store. | What we held by T. A backfill run in 2026 carries a 2026 value here regardless of when the filing was made. |

The response envelope repeats `as_of` and `visible_by`. This records the exact query parameters with the stored result.

## Rows with a null clock

If a row has a null value for the selected clock, the query excludes that row. If the null value is systematic rather than incidental, the day is listed in `coverage.missing`. The API returns HTTP 409 with `count` set to JSON null. For example, querying the 2023-03-10 SEC data with `visible_by=available_at` returns HTTP 409 and lists `availability.sec.edgar/2023-03-10` instead of returning a partial list of rows.

## became_knowable

`became_knowable(T0, T1)` returns the rows that became visible between T0 and T1 on the same clock. Query this set using `GET /v1/news/diff` with `as_of_start` and `as_of_end`. This differs from filtering rows where `event_at` falls between the two timestamps, and it differs from returning all rows visible at T1.

## In the Python client

In the Python client, `query_as_of(..., known_at=...)` maps to `GET /v1/news` with `as_of`. Using `as_of=` directly raises a `TypeError`. The `as_of` parameter is required for paid historical reads.

## Related

- [Clock policy](https://pit.aqx.llc/docs/clocks)
- [Lookahead bias](https://pit.aqx.llc/glossary/lookahead-bias)
- [Coverage certificate](https://pit.aqx.llc/glossary/coverage-certificate)
- [Point-in-time SEC filings API](https://pit.aqx.llc/use/sec-8k-as-of)