Skip to Content
PredictorSDK

GET /v1/markets now tells you how old the catalog is

NewSDK

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.