Polymarket Historical Data API — Prices, Metrics & L2 Order Books

Overview guides: For walkthroughs and samples, see Polymarket historical data, order book data, and 5-minute markets.

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. Endpoint reference for individual routes lives in the OpenAPI spec (/openapi.json). This page covers concepts; use the spec for request/response fields.

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)

1s resolution is available on every plan. On Starter, 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=1s"

Response (abbreviated)

{
  "market_id": "618831",
  "resolution": "1s",
  "tokens": {
    "Yes": "0xabc...",
    "No": "0xdef..."
  },
  "data": {
    "Yes": [{ "t": "2026-07-26T00:00:00Z", "bids": [[0.19, 147.34], [0.18, 63.69]], "asks": [[0.2, 13.6], [0.21, 152.17]] }],
    "No": [{ "t": "2026-07-26T00:00:00Z", "bids": [[0.8, 152.17], [0.79, 13.6]], "asks": [[0.81, 63.69], [0.82, 147.34]] }]
  },
  "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>[].bids` / `.asks`	Bid and ask ladders on `/books` endpoints — `[price, size]` pairs, best price first
`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

Backtest AI

Reference

Polymarket Historical Data API — Prices, Metrics & L2 Order Books

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