How do I download Polymarket historical data?

GET /v1/markets/{market_id}/export returns a 302 redirect to a presigned URL for a Parquet file of order book snapshots, deltas, and trades. Use the Python SDK's client.exports.download(market_id) or curl -L. See marketlens.trade/docs/exports.

Can I download a whole series of markets at once?

Yes. GET /v1/series/{series_id}/export returns a JSON manifest with one presigned URL per ready market plus the list of markets still building. See marketlens.trade/docs/exports#series-export.

How is bulk export billed?

Exports charge data rows against your plan's row allowance, once per file ever: a file you already unlocked charges zero rows on later downloads. There is no separate cap on the number of exports per day. See marketlens.trade/docs/errors.

Data

Exports

Order book history as Parquet, served via presigned download URLs.

GET/markets/{market_id}/export

sdkclient.exports.download(market_id)

Order book history (snapshots, deltas, trades) for a single market as a Parquet file. Returned as a 302 redirect to a presigned URL valid for one hour. The file's rows are charged against your data row allowance the first time only; a file you already unlocked charges zero rows on every later request.

Parameters

market_idstrrequired

Market UUID.

data_dirstr | PathLike= "."

SDK only. Directory to write the Parquet into. Created if missing.

coalescebool= false

Trade-aligned compact variant. Book reconstructed from it is exact at every trade and snapshot.

client.exports.download(
    "4ee145e2-3fee-5b15-bb95-56a33a292945",
    data_dir="data",
)
result = client.backtest(
    strategy, "4ee145e2-3fee-5b15-bb95-56a33a292945",
    initial_cash=10_000,
    data_dir="data",
)

http

HTTP/1.1 302 Found
Location: https://hel1.your-objectstorage.com/marketlens/history/...
X-Export-Rows: 92866
Cache-Control: no-store

GET/series/{series_id}/export

sdkclient.exports.download_series(series_id, **params)

Order book history for every market in a series, with one presigned URL per ready market. Each market's file charges its row count the first time you unlock it; markets you already unlocked appear with rows: 0 and cost nothing, so polling a series for newly built markets is free. Markets whose first unlock does not fit your remaining row balance are listed under rate_limited without URLs. Pass dry_run first to see the exact cost of a window before spending it.

Parameters

series_idstrrequired

Series slug or UUID.

data_dirstr | PathLike= "."

SDK only. Directory to write each market's Parquet into. Created if missing.

afterint | str

Window start (ms epoch or ISO 8601).

beforeint | str

Window end (ms epoch or ISO 8601).

coalescebool= false

Trade-aligned compact variant. Book reconstructed from it is exact at every trade and snapshot.

dry_runbool= false

Cost preview. Same manifest with no download URLs; nothing billed or unlocked, and rows_charged is an exact quote.

client.exports.download_series(
    "btc-up-or-down-5m",
    data_dir="data",
    after="2026-04-15T01:45:00Z",
    before="2026-04-15T01:50:00Z",
)
result = client.backtest(
    strategy, "btc-up-or-down-5m",
    initial_cash=10_000,
    after="2026-04-15T01:45:00Z",
    before="2026-04-15T01:50:00Z",
    data_dir="data",
)

jsonResponse

{
  "ready": [
    {
      "market_id": "4ee145e2-3fee-5b15-bb95-56a33a292945",
      "url": "https://hel1.your-objectstorage.com/marketlens/history/...",
      "events": 92866,
      "rows": 92866
    },
    {
      "market_id": "8b6f1a02-9c3d-4e7a-b1f8-2a9d4c5e6f70",
      "url": "https://hel1.your-objectstorage.com/marketlens/history/...",
      "events": 81234,
      "rows": 0
    }
  ],
  "pending": [],
  "failed": [],
  "rate_limited": [],
  "events_charged": 174100,
  "rows_charged": 92866
}

GET/markets/{market_id}/orderbook/metrics/export

sdkclient.exports.download_market_bars_batch(market_ids, **params)

Order-book metrics or OHLCV candles for a single market at one resolution, as a Parquet file. Returned as a 302 redirect to a presigned URL.

Parameters

market_idstrrequired

Market UUID.

resolutionstrrequired

Bucket size. 1m to 1d for metrics; 1s to 1d for candles.

pricestr= "mid"

SDK only. "mid" for the metrics export, "close" for the candles export.

data_dirstr | PathLike= "."

SDK only. Directory to write each Parquet into. Created if missing.

concurrencyint= 1

SDK only. Parallel downloads in the batch helper.

bars = client.exports.download_market_bars_batch(
    ["4ee145e2-3fee-5b15-bb95-56a33a292945"],
    resolution="1m",
    price="mid",
    data_dir="bars",
)
result = client.backtest(
    strategy, "4ee145e2-3fee-5b15-bb95-56a33a292945",
    initial_cash=10_000,
    resolution="1m",
    data_dir=bars,
)

http

HTTP/1.1 302 Found
Location: https://hel1.your-objectstorage.com/marketlens/metrics/...

Auto-download

Backtest directly against the bulk export, no separate download step required. The first run fetches the files to disk; subsequent runs replay from the local cache. The signal backtest works the same way, downloading bar Parquet on the first run.

python

# downloads on first run, replays from cache after
result = client.backtest(
    strategy, "btc-up-or-down-5m",
    initial_cash=10_000,
    after="2026-04-15T01:45:00Z",
    before="2026-04-15T01:50:00Z",
    data_dir="data",
)