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 against your daily event budget — one row equals one event. 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.

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-Events: 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.

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.

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
    },
    {
      "market_id": "8b6f1a02-9c3d-4e7a-b1f8-2a9d4c5e6f70",
      "url": "https://hel1.your-objectstorage.com/marketlens/history/...",
      "events": 81234
    }
  ],
  "pending": [],
  "failed": [],
  "rate_limited": [],
  "events_charged": 174100
}

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",
)