Orderbook Snapshots
The full bid and ask ladder for a market at a point in time: every price level and every size, not just the top of book. Stored as Parquet, one file per market per day.
How often
Snapshots are taken on a tier set by how close the market is to its end. Markets are re-tiered every five minutes, so a market speeds up as it nears expiry. Other venues are captured about every five minutes.
| Time to expiry | Snapshot interval |
|---|---|
| Under 1 hour | Every 5 seconds |
| Under 24 hours | Every 30 seconds |
| Under 1 week | Every 60 seconds |
| 1 week or more | Every 15 minutes |
Columns
Each row is one outcome token's book at one moment, so a binary market produces two rows per tick.
| Column | Meaning |
|---|---|
| timestamp | When the snapshot was taken, UTC, as an ISO-8601 string. |
| market_id | The market's condition id, a 0x hash. It is not the numeric markets.id you request with. |
| token_id | The outcome token this book belongs to. A binary market has one book per token. |
| outcome | The outcome's label, for example Yes or Up. |
| question | The market question. |
| market_slug | The market's slug. |
| end_date | The market's scheduled end. |
| bids | Every bid level, as JSON text: a list of price and size pairs. |
| asks | Every ask level, in the same form. |
| best_bid | Highest bid price. Null when the book has no bids. |
| best_ask | Lowest ask price. Null when the book has no asks. |
| mid_price | Midpoint of best bid and best ask. |
| spread | best_ask minus best_bid. |
| spread_pct | The spread as a percentage of the midpoint. |
| bid_depth | Sum of price times size across the bid levels. |
| ask_depth | Sum of size across the ask levels. |
| bid_levels | Number of bid levels. |
| ask_levels | Number of ask levels. |
| source | Where the snapshot came from. |
| snapshot_interval | The cadence tier it was taken on, for example 5s. |
Pulling it
Request a market by its numeric markets.id, such as 1254468. The market_id inside a snapshot row is a different identifier, the 0x condition id, and a hex id is not accepted in a request.
| Endpoint | Parameters | Returns |
|---|---|---|
| GET /v1/download/orderbook | market_id, start, end, format, limit | The full ladder for one market. Included with the Professional plan. |
| GET /v1/download/top_of_book | market_id, start, end (all required), format | The free preview: best bid, best ask, midpoint and spread only. Delayed 24 hours, last 30 days, and counted against the Free plan's 10 MB monthly export. |
| GET /v1/download/raw | data_type=polymarket_l2_deltas, start, end (both required) | The raw delta tape: every book change as the venue sent it, captured live since June 2026. Included with the Professional plan. |
GET /v1/download/raw/datasets lists every raw stream and the data_type to pass for it. Parameters, limits and errors are in the API reference, and what each plan includes is on the pricing page.