> ## Documentation Index
> Fetch the complete documentation index at: https://docs.polyhistorical.com/llms.txt
> Use this file to discover all available pages before exploring further.

# Parquet Downloads

> Download whole markets as Parquet files and read them in Python, DuckDB, or Excel

# 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](https://docs.polyhistorical.com/api-reference/get-snapshots.md), and the files are small: a 5-minute BTC market with around 2,600 snapshots is under 200 KB.

> [!NOTE]
>
> Parquet downloads are included with **Pro**, **Suite**, and **Enterprise** plans. You can download any market inside your plan's [data window](https://docs.polyhistorical.com/guides/pricing.md).

## 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](https://docs.polyhistorical.com/api-reference/get-snapshots.md). 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`](https://docs.polyhistorical.com/api-reference/download-snapshots). To find slugs, use [List Markets](https://docs.polyhistorical.com/api-reference/list-markets.md).

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](https://docs.polyhistorical.com/guides/rate-limits.md)

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](https://docs.polyhistorical.com/api-reference/get-snapshots.md) returns them:

```json theme={null}
{
  "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 }]
}
```

> [!NOTE]
>
> Decimal columns keep exact values. pandas reads them as Python `Decimal` objects; convert with `.astype(float)` if you prefer floats.

## Reading files

```python pandas theme={null}
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])
```

```python Polars theme={null}
import polars as pl

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

```bash DuckDB theme={null}
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:

```bash theme={null}
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:

```bash theme={null}
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:

```python theme={null}
import json
import pyarrow.parquet as pq

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


This documentation is built and hosted on [Mintlify](https://mintlify.com), a developer documentation platform.