Historical overview

Historical endpoints return bucketed time series for a market or token within a half-open interval [start_ts, end_ts). Data is materialized from sparse historical captures into uniform buckets using last-value carry — each bucket reflects the most recent known value at or before that timestamp. All historical routes require X-API-Key on the hosted API and enforce your plan’s resolution floor and history window — see Pricing.

Endpoints

Method	Path	Returns
`GET`	`/v1/markets/{id_or_slug}/prices`	Outcome-labeled price series
`GET`	`/v1/markets/{id_or_slug}/metrics`	Volume, liquidity, spread
`GET`	`/v1/markets/{id_or_slug}/books`	L2 order book snapshots per outcome
`GET`	`/v1/tokens/{token_id}/prices`	Single-token price series
`GET`	`/v1/tokens/{token_id}/books`	Single-token order book series

Required parameters

Parameter	Description
`start_ts`	Inclusive window start — ISO-8601 UTC or Unix seconds
`end_ts`	Exclusive window end — ISO-8601 UTC or Unix seconds
`resolution`	Bucket width — see Resolutions

Optional: limit (default 100, max 200) and cursor for paginated series.

end_ts is exclusive. To query July 26 00:00 through July 26 23:59 inclusive at 1h resolution, set end_ts to 2026-07-27T00:00:00Z.

Example — market order books (Starter)

On Starter, use resolution=60s and keep start_ts within the last 7 days:

curl -s -H "X-API-Key: $POLYORDERBOOKS_API_KEY" \
  "https://api.polyorderbooks.com/v1/markets/MARKET_SLUG/books" \
  --get \
  --data-urlencode "start_ts=2026-07-26T00:00:00Z" \
  --data-urlencode "end_ts=2026-07-26T06:00:00Z" \
  --data-urlencode "resolution=60s"

Response (abbreviated)

{
  "market_id": "618831",
  "resolution": "60s",
  "tokens": {
    "Yes": "0xabc...",
    "No": "0xdef..."
  },
  "data": {
    "Yes": [{ "t": "2026-07-26T00:00:00Z", "b": [[0.54, 1000]], "a": [[0.56, 800]] }],
    "No": [{ "t": "2026-07-26T00:00:00Z", "b": [[0.44, 900]], "a": [[0.46, 1100]] }]
  },
  "metadata": {
    "count": 1,
    "limit": 100,
    "next_cursor": null
  }
}

Field reference

Field	Description
`data.<outcome>[].t`	Bucket timestamp (UTC, ISO-8601)
`data.<outcome>[].p`	Price in [0, 1] on `/prices` endpoints
`data.<outcome>[].b` / `.a`	Bid and ask ladders on `/books` endpoints
`metadata.next_cursor`	Pagination token when more buckets exist

When to use token endpoints

Use token-level routes when you already have a CLOB token id:

Resolutions

Bucket sizes and plan restrictions.

Pagination

Cursor-based paging for long ranges.

Rate limits

Quotas and efficient bulk retrieval.

Getting started

Discovery

Historical

Reference

Endpoints

Required parameters

Example — market order books (Starter)

Field reference

When to use token endpoints

Resolutions

Pagination

Rate limits

​Endpoints

​Required parameters

​Example — market order books (Starter)

​Field reference

​When to use token endpoints

​Related guides

Resolutions

Pagination

Rate limits

Endpoints

Required parameters

Example — market order books (Starter)

Field reference

When to use token endpoints

Related guides