GET /v1/markets now tells you how old the catalog is
GET /v1/markets returned exactly two top-level keys — data and
pagination — and no timestamp anywhere. The endpoint reads a stored catalog
snapshot rather than calling the venues, so "how old is this page" had no
answer and was not "now": a page of 1.76 million rows could have been crawled
ten seconds or two hours ago and looked identical either way.
Every response now carries a snapshot block:
{
"data": [ ],
+ "snapshot": {
+ "observed_at": "2026-08-25T13:41:22.108Z"
+ },
"pagination": {
"limit": 25,
"total": 1393200,
"has_more": true,
"next_cursor": "eyJzIjoiNDQxMzZmYTMi..."
}
}It sits beside data, not inside pagination, because it describes the data
rather than how the page was cut.
What the value means. observed_at is when PredictorSDK finished reading
the catalog — the same meaning it already carries on pricing.observed_at and
trading_fees.observed_at, and deliberately not as_of, which is reserved for
a venue's own stamp. The difference from those two is which read: they stamp
the upstream call your request made, while this stamps the background ingestion
crawl that built the snapshot, so it is normally minutes to hours old rather
than milliseconds.
It is a floor, and ?provider= makes it exact. Providers are crawled on
independent schedules, so the catalog is a merge of snapshots of different ages
and the published number is the OLDEST of them. Every row on the page is at
least that fresh; most are fresher. Under ?provider= the value is that
provider's own read time, the same way pagination.total already counts only
the filtered set — so filtering is the cheapest way to trade a conservative
bound for an exact one.
It does not move during a traversal. A market cursor stays bound to the
immutable snapshot that issued it, so every page of one traversal reports the
identical observed_at even while newer snapshots publish behind you. Start a
fresh first page to see a newer one.
observed_at is null when the bound snapshot carries no read time — treat
that as unknown age, not as fresh.
The TypeScript, Python and Go SDKs gain a MarketsSnapshot type on the list
response; the field is a parsed date-time, not a string. Nothing was removed
and no existing field changed, so a client that ignores the new block keeps
working.