GET/v1/markets/:id/snapshots

Get Market Snapshots

Paginated time-series orderbook snapshots for a specific market. Rows carry category/subcategory/label for identity; crypto and crypto_price appear only on crypto-category markets (omitted on sports/weather/equities — the underlying spot price only exists for crypto). Raw rows (default and includebook modes) also carry four data-fidelity fields — event_timestamp (Polymarket emit time), capture_timestamp (our store time; the difference is ingestion latency), sequence_number (per-token count of orderbook events APPLIED by the collector — capture keeps ~1 row per 50ms and drops unchanged books, so gaps between adjacent rows are the normal case, not dropped data; it also resets on re-subscribe and is 0 on backfilled rows, so do not build gap detection on it) and crypto_price_age_ms (spot-price staleness, -1 when untracked) — matching /api/snapshot?includebook=true. These are NOT present on interval (OHLC candle) rows. LONG-LIVED markets (months of data): unwindowed queries can take ~25s, 500 on timeout, or return total:null when only the count sub-query times out (data rows still valid) — pass explicit from/to windows or use interval= candles for those.

Path Parameters

idstringrequired

Market ID (conditionId)

Query Parameters

formatstringdefault:json

Response encoding. csv and tsv return the row array as a flat file instead of a JSON envelope — the envelope moves to X-* response headers and nulls render as \N. REQUIRES SCALE OR ENTERPRISE (json is available on every tier). Works with includebook=true — the bids/asks ladders come through as compact JSON inside their cell, complete and parseable (pandas: df["bids"].apply(json.loads)).

sidestring

Token side filter

fromstring

Start timestamp

tostring

End timestamp

intervalstring

Downsample to OHLC candles instead of raw rows. Each bucket returns open/high/low/close/vwap_mid plus avg spread, depth and a snapshot_count — one candle per (bucket × token_side). Turns a 200k-row pull into a few thousand rows: a 4-day market at 500ms cadence goes from ~89k rows (18 pages) to ~1.5k candles in a single call. Cannot be combined with includebook or touchsize — a candle aggregates many books, so it carries neither the ladders nor a single touch level; both combinations return 400.

limitnumberdefault:500

Max rows, default 500. The ceiling depends on the mode: 5000 raw, 2000 with includebook=true (rows are ~10x heavier), 50000 with interval= (candles are tiny). Over the ceiling is a 400 naming it — never a silent clamp, so a page never comes back quietly short.

offsetnumberdefault:0

Pagination offset

includebookbooleandefault:false

Include full bid/ask arrays in each row. Off by default for payload size; turn on when you need depth. Drops the limit ceiling to 2000 and cannot be combined with interval.

touchsizebooleandefault:false

Add best_bid_size and best_ask_size — the size resting AT the best bid/ask, in SHARES. Note bid_depth_total/ask_depth_total are whole-book totals in DOLLARS, a different question; dollars capturable at the touch = best_bid_size * best_bid. Off by default: recent partitions store these columns (~1.3x a scalar read) while older ones compute them from the stored book arrays (~3x), so opting in keeps normal queries on the cheap path. Free and automatic with includebook=true. An unquoted side reports 0. Only valid on this endpoint, and cannot be combined with interval (a candle aggregates many books, so it has no single touch level) — both misuses return 400 rather than a 200 with the fields missing.

orderstringdefault:desc

Sort by timestamp: asc/oldest (chronological) or desc/newest (reverse). Defaults to desc.

contextstring

Set to "replay" to apply free-tier replay quota gating

Response

200401403404500

Successful Response

Code Snippet

curl -X GET "https://api.resolvedmarkets.com/v1/markets/:id/snapshots" \
  -H "X-API-Key: YOUR_API_KEY"

200

{
  "market_id": "0x...",
  "total": 5400,
  "limit": 100,
  "offset": 0,
  "data": [
    {
      "timestamp": "2026-03-02 15:30:00.123",
      "token_side": "UP",
      "best_bid": 0.52,
      "best_ask": 0.53,
      "event_timestamp": "2026-03-02 15:30:00.081",
      "capture_timestamp": "2026-03-02 15:30:00.123",
      "sequence_number": "148213",
      "crypto_price_age_ms": 42
    }
  ]
}