# GET /v1/markets now tells you how old the catalog is (https://docs.predictorsdk.com/changelog/2026-08-26-markets-snapshot-observed-at)

2026-08-26 · New, SDK

`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:

```diff
  {
    "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.