- JSON ·
CSV · JSONLOutput formats - Full bookSnapshot fields
- Up to 5,000Page size
- rm-api CLIBulk export
Almost every prediction-market analysis starts the same way: get the data into a DataFrame. This post covers the two clean routes, query the REST API row by row, or bulk-export to CSV with the CLI and load it in one line, and the snapshot fields you will actually use once it is in memory.
There is nothing exotic here, and that is the point. The snapshots come back as plain JSON records with stable field names, so they map straight onto a DataFrame with no custom parsing. The only real decision is how you fetch them.
Two ways to get the data
REST, row by row
Hit the snapshots endpoint with a market id and a time range, page through the results, and build the frame in memory. Best for recent or targeted pulls from the archive.
- Filter by side and time
- Optional full book per row
- Up to 5,000 rows per page
CLI bulk export
The rm-api CLI downloads a window straight to CSV or JSONL, so you load the whole file with one read. Best for larger research jobs.
- CSV, JSON, or JSONL
- Incremental SQLite sync
- One-line load in pandas
The fields that matter once it is loaded
- best_bid, best_ask, mid_price, spread, the derived prices you will chart and signal on.
- bid_depth_total, ask_depth_total, pre-computed depth, so you do not have to sum the book yourself.
- bids and asks arrays, the full ladder, available when you ask for the book, for honest fill modelling.
- timestamp plus event and capture timestamps, so you can index by time and reason about latency.
- crypto_price, the spot reference stamped on each crypto snapshot, ready to join against the odds.
Stable field names, no custom parser
Because every snapshot uses the same field names across markets and timeframes, the same loader works for BTC 5-minute books and daily weather markets alike. Set the timestamp as the index, sort, and you are ready to resample, join, and plot.
Which route fits your job
The choice between paging the REST API and bulk-exporting with the CLI is really a question of scale and freshness. A quick dashboard or a one-off look at the last hour wants the REST route, small, targeted, current. A research job that touches weeks of book history wants the CLI: one download, one file, no pagination bookkeeping. Both end in the same DataFrame, so you can start with REST and graduate to the CLI without rewriting your analysis.
- 1Pick a market by id, or resolve a friendly slug like btc-updown-1h to its conditionId first.
- 2Choose a side, UP or DOWN, and a time window with from and to.
- 3Decide whether you need the full ladder: include_book pulls the bids and asks arrays per row; leave it off for just the derived prices and depth totals.
- 4Page in chunks of up to 5,000 rows with limit and offset, or skip pagination entirely by exporting the window to a flat file with the CLI.
- 5Load into pandas, set the timestamp index, sort, and resample to whatever bar size your study needs.
What you can do once it is a frame
Resample the odds
Roll the mid-price into 1-minute or hourly bars to chart how implied probability moved through an event.
- OHLC on mid_price
- Align to crypto timeframes
- Plot odds over time
Study spread and depth
The pre-computed spread and depth totals make liquidity analysis a one-liner, no summing the ladder by hand.
- Spread distributions
- Depth imbalance
- Liquidity over the session
Join odds to spot
Each crypto snapshot carries a spot reference price, so you can line the market’s odds up against BTC or ETH directly.
- crypto_price column
- Merge on timestamp
- Lead/lag studies
Event time and capture time
Each snapshot stamps both when Polymarket emitted the change and when we recorded it. Index on event time for analysis that should follow the market’s own clock; keep capture time around when you want to measure end-to-end latency or audit the feed.
The DataFrame is never the hard part. Clean, consistently-named snapshots are, and that is the part we have already done for you.
Pull your first frame
The docs show the snapshots endpoint and every query parameter; the data pages show what each category contains.
Frequently asked questions
Can I export Polymarket data to CSV?
Yes. The rm-api CLI exports snapshot windows to CSV, JSON, or JSONL, which load directly into pandas, R, or a spreadsheet. You can also page the REST snapshots endpoint and build the DataFrame in memory if you prefer to stay in Python.
What columns does a snapshot DataFrame have?
Each row carries the derived prices (best_bid, best_ask, mid_price, spread), pre-computed depth totals (bid_depth_total, ask_depth_total), timestamps (event and capture), and the spot crypto_price reference. Request the book and you also get the full bids and asks arrays per row.
Is the data available without writing code?
Yes, the CLI produces CSV/JSONL files you can open in any tool, and the dashboard lets you browse markets visually. The REST API is there when you want to automate the pull, but it is not required just to get the data into a spreadsheet.
How far back can I pull snapshots into a DataFrame?
On the Free tier you can pull all crypto coins at full depth with unlimited history; the rate and credit allowance set the practical pace. The canonical archive holds 700M+ snapshots, so for large historical pulls the CLI bulk export is usually faster and cheaper on credits than paging the REST endpoint thousands of times.