Parquet Downloads

Every finished market is available as one Parquet file with all of its snapshots and full order books. Downloading a file is faster than paging through Get Snapshots, and the files are small: a 5-minute BTC market with around 2,600 snapshots is under 200 KB.

Parquet downloads are included with Pro, Suite, and Enterprise plans. You can download any market inside your plan’s data window.

When to use it

You want every snapshot of a market, not one page at a time
You’re building a dataset across many markets for backtesting or research
You work in pandas, Polars, DuckDB, Spark, or another tool that reads Parquet

For a market that’s still running or has only just ended, use Get Snapshots. Files are created after a market ends, usually within a day.

Getting files

Request a market’s file by slug with GET /v1/markets/{slug}/snapshots/download. To find slugs, use List Markets. The endpoint returns a download link (url) instead of the file itself. The link:

works without your API key, so don’t send the key to it
expires after 10 minutes; ask the endpoint again for a fresh link
doesn’t count against your rate limit

The response also has sha256 and size_bytes, so you can check the file arrived intact.

File contents

One file holds one market. There’s one row per snapshot, in time order (oldest first). Each row has the market’s details followed by the snapshot data, so the file makes sense on its own in any tool. Files are compressed with zstd.

Market columns

These are the same on every row of a file.

Column	Type	Description
`slug`	string	Market slug
`coin`	string	`BTC`, `ETH`, or `SOL`
`market_type`	string	`5m`, `15m`, `1h`, `4h`, or `24h`
`market_id`	string	Polymarket market ID
`event_id`	string	Polymarket event ID
`condition_id`	string	Polymarket condition ID
`clob_token_up`	string	CLOB token ID of the “Up” outcome
`clob_token_down`	string	CLOB token ID of the “Down” outcome
`start_time`	timestamp (UTC)	Market start time
`end_time`	timestamp (UTC)	Market end time
`coin_price_start`	decimal(20, 8)	Coin price at market start
`coin_price_end`	decimal(20, 8)	Coin price at market end
`winner`	string	`Up` or `Down`
`final_volume`	decimal(20, 2)	Final traded volume
`final_liquidity`	decimal(20, 2)	Final liquidity
`is_resolved`	boolean	Whether the market has resolved
`resolved_at`	timestamp (UTC)	When the market resolved

Snapshot columns

Column	Type	Description
`time`	timestamp (UTC, microseconds)	Snapshot time
`coin_price`	decimal(20, 8)	Coin price at snapshot time
`price_up`	decimal(10, 6)	Price of the “Up” outcome (0-1)
`price_down`	decimal(10, 6)	Price of the “Down” outcome (0-1)
`orderbook_up`	string (JSON)	Order book for the “Up” outcome
`orderbook_down`	string (JSON)	Order book for the “Down” outcome
`volume`	decimal(20, 2)	Market volume at snapshot time
`liquidity`	decimal(20, 2)	Market liquidity at snapshot time

Order books are stored as JSON text, in the same shape as Get Snapshots returns them:

{
  "asks": [{ "size": 168.54, "price": 0.61 }, { "size": 37.0, "price": 0.62 }],
  "bids": [{ "size": 120.0, "price": 0.60 }, { "size": 55.5, "price": 0.59 }]
}

Decimal columns keep exact values. pandas reads them as Python Decimal objects; convert with .astype(float) if you prefer floats.

Reading files

import json
import pandas as pd

df = pd.read_parquet("btc-updown-5m-1788140100.parquet")
print(len(df), "snapshots")

numeric = ["coin_price", "price_up", "price_down"]
df[numeric] = df[numeric].astype(float)
print(df[["time", *numeric]].head())

book = json.loads(df.orderbook_up.iloc[0])
print(book["asks"][:3])

import polars as pl

df = pl.read_parquet("btc-updown-5m-1788140100.parquet")
print(df.select("time", "coin_price", "price_up", "price_down").head())

duckdb -c "SELECT time, coin_price, price_up, price_down
           FROM 'btc-updown-5m-1788140100.parquet' LIMIT 10"

# Read the order book with DuckDB's JSON functions
duckdb -c "SELECT time, orderbook_up->'asks'->0->>'price' AS best_ask_up
           FROM 'btc-updown-5m-1788140100.parquet' LIMIT 10"

pandas needs pyarrow installed (pip install pandas pyarrow). DuckDB is available with brew install duckdb or pip install duckdb. Timestamps are stored in UTC. DuckDB displays them in your computer’s time zone; run SET TimeZone = 'UTC'; first to see UTC.

Many files at once

DuckDB and Polars can query a whole folder of files as one table:

duckdb -c "SELECT slug, winner, count(*) AS snapshots, min(price_up), max(price_up)
           FROM 'markets/*.parquet' GROUP BY slug, winner ORDER BY slug"

Converting to CSV

To open a file in Excel, Numbers, or Google Sheets, convert it to CSV:

duckdb -c "COPY (SELECT * FROM 'btc-updown-5m-1788140100.parquet') TO 'btc-updown-5m-1788140100.csv' (HEADER)"

CSV files are about 30 times larger than the Parquet file, mostly because of the order books.

Market details in the file metadata

The file’s Parquet metadata also stores the full market object as JSON under the key market. You don’t need it, since the market columns hold the same information, but it’s there if your tooling reads metadata:

import json
import pyarrow.parquet as pq

meta = pq.ParquetFile("btc-updown-5m-1788140100.parquet").metadata.metadata
market = json.loads(meta[b"market"])

Getting Started

API Reference

Guides

Parquet Downloads

Parquet Downloads

When to use it

Getting files

File contents

Market columns

Snapshot columns

Reading files

Many files at once

Converting to CSV

Market details in the file metadata

​Parquet Downloads

​When to use it

​Getting files

​File contents

​Market columns

​Snapshot columns

​Reading files

​Many files at once

​Converting to CSV

​Market details in the file metadata

Parquet Downloads

When to use it

Getting files

File contents

Market columns

Snapshot columns

Reading files

Many files at once

Converting to CSV

Market details in the file metadata