as_of and nothing changes. Supply it and the endpoint reconstructs the
answer from the chain snapshot in force at that instant.
Where it works
Start with
/v2/options/chain if you would rather
compute your own views: it returns the raw contracts as they stood, and every
other endpoint above is derived from exactly that snapshot.
The two flow endpoints differ from the rest. They return a series across
snapshots, so as_of sets where that series ENDS rather than naming a single
point. Each frame in it carries the tape as of that frame.
For historical price, open interest, funding, CVD and liquidations, use
/v2/market/*, which is built for time series.
It snaps backward, never forward
Chains are persisted roughly every five minutes, so an arbitrary timestamp will not land on one exactly.as_of resolves to the nearest snapshot at or
before the time you asked for.
Never after. Snapping forward would let a backtest see a chain from after the
moment it is meant to be trading, which makes a strategy look better than it
is. Snapping backward can only ever be slightly stale, which is honest and
measurable.
The response tells you exactly what you got:
snapshot_ts, not on what you requested.
Flow positioning is rebuilt as of that moment
Under the defaultpositioning=flow, the dealer flow map is reconstructed
from the aggressor tape as it stood at that instant rather than from
today’s tape. A given timestamp therefore returns the same numbers every time
you ask, which is what makes the series usable for research.
Values are rounded before they are returned. The same aggregate run twice can
differ in its last bits, which is meaningless as a quantity and unacceptable
in something you are meant to be able to re-run.
Coverage
Both sources are bounded by when ingestion began, not by a retention policy, and they do not start on the same day.
An
as_of between those two dates has a chain but no tape. The response is
signed with the textbook std convention instead and says so:
404 rather than the oldest snapshot we
happen to hold.
Nothing is borrowed from live
Anas_of response never contains a current value wearing a past timestamp.
On /v2/gex/levels, max_pain and expected_move are
recomputed from the snapshot rather than read from the live caches that back
them normally.
Where an honest answer is not possible, the section is omitted and named:
include=spot and include=candles come from the perpetual candle series, a
different source with its own history. Back-dating a price from an options
snapshot would be inventing one.
Your plan’s window applies
as_of is bounded by the same history entitlement as days and hours. A
timestamp outside your window is clamped, never rejected, and reported:
Practical notes
- A timestamp far in the past is not an error, it is a 404 when history does not reach it. Check the coverage table before assuming a gap.
- Repeated requests are cheap. Answers are cached on the resolved snapshot, so sweeping a window pays for each snapshot once no matter how many distinct timestamps you send.
- Future timestamps are rejected with
400. Omitas_offor the current value.