Point in time
A question about the past is answered with what had been recorded as of that instant, not with what is known now. The same question asked again returns the same answer. This page defines the terms that make that true, one row each, and says where each is used.
The definitions
Section titled “The definitions”| term | what it is | where |
|---|---|---|
as_of (as of in DQL) |
The instant an answer describes. Everything the platform had received by then is visible; nothing received after it is. | POST /v2/screen (as of in the query), GET /v2/instruments?as_of=, at in POST /v2/snapshots/history, as_of in POST /v2/candles, /v2/liquidations and /v2/trades |
| Received-time cut-off | A value counts only if its received_at is at or before the cut-off. A value stamped after it, by a collector whose clock runs ahead for instance, is never shown in the answer and never in its replay. Order between venues and layers is received_at, never the order answers reached the client. |
as_of on candles, liquidations and trades; served_at in a replay |
venue_ts and received_at |
Two different times. venue_ts is the venue’s own timestamp, stored as the venue sent it; received_at is when the platform received the value. age_ms is counted from the venue’s time where the venue dates the value, from received_at otherwise. |
every value |
served_at and receipt_id |
served_at is an answer’s own as-of instant, receipt_id names that exact answer. A replay with as_of = served_at returns what had been recorded as of that instant, the same every time. |
every answer that carries data |
| Sampling window | History keeps the last reading of every sampling window, and a stored reading counts from the end of its window. history_cadence on GET /v2/instruments says how long the window is for each layer of a listing. |
GET /v2/instruments |
settled |
Whether the instant is far enough in the past that a late arrival can no longer change the answer. A false is not an error: it means the same query may answer differently later. |
every historical answer |
A live answer shows the newest reading received by served_at. History shows what was stored, so a live answer can be one reading ahead of history until that reading’s sampling window closes. A replay is the tool for a post-mortem, not a copy of the live answer; once the window has ended the two agree field for field. Order books are not replayable, because levels are never stored.
Revisions
Section titled “Revisions”A past answer can change only in the ways the platform says it can. Each is named in the answer.
| what can change | how it is named |
|---|---|
| The mapping of a venue symbol to an instrument, base and quote | Each row carries the mapping valid at its own instant: instrument, base, quote, multiplier. identity_basis says whether the mapping interval was recorded or reconstructed; identity_corrected_at is when a later one began. See Identity over time. |
| The set of listings and what each venue publishes | listings_as_of and capabilities_as_of say when each was last known to change. registry_revision identifies the registry snapshot every page of a GET /v2/venues or GET /v2/instruments read shared. |
The rules a quantity was converted by (units: base) |
normalisation_version is present with every units: base answer. Two figures under different versions were converted by different rules. |
| A day’s anchored history | The daily root posted to Base is a revision of the day. Revision 0 is the day as anchored; a correction would be a revision of its own with its own root. See Verify an anchor. |
Gaps come back as gaps
Section titled “Gaps come back as gaps”History is stored with its holes intact. A period nobody quoted is empty, never interpolated and never carried forward.
| where | how a gap is written |
|---|---|
interval history |
A row with status gap and its reason: no_value, or collector_gap with a gap_cause where the platform recorded a hole. |
raw history |
The stretches the range missed are listed under gaps, each with reason collector_gap (and gap_cause) or not_retained. |
at history |
A reading over the freshness bound is stale or missing; gap_cause says what the platform recorded. |
| Candles | A gap row for a period with no candle. A longer period exists only when every base minute of it exists. |
| Trades and liquidations | gaps lists the stretches the list is known to be incomplete, and truncated says the newest events were returned. Read gaps before treating an empty stretch as a quiet market. |
| Before the first stored instant | not_retained, with the earliest instant kept for the listing in retention_from. |
The one exception is a value a venue pushes only on change. While its connection lives it is carried into the periods it holds for, and says carried: true; once the connection was lost it is stale with reason connection_lost. How long each value is good for is on Freshness and cadence; every status and reason is on Statuses and reasons.
An example
Section titled “An example”On 2026-09-27 at 20:17:14.729 UTC the collector serving Binance went down. Asked what the Binance ticker was 0.8 seconds later, with at, history answers stale, reason connection_lost, gap_cause: collector_down, no value, and the time the last value was received and until when it was good. The request and the full answer are in Check it yourself.