> ## 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.

# Download Snapshots

> Get a download link for a market's full snapshot history as a Parquet file

# Download Snapshots

Returns a short-lived download link to one market's **complete snapshot history** as a single [Parquet file](https://docs.polyhistorical.com/guides/parquet-files.md). Every snapshot of the market is in the file, with full order books, so you don't need to page through [Get Snapshots](https://docs.polyhistorical.com/api-reference/get-snapshots.md).

> [!NOTE]
>
> Requires a **Pro**, **Suite**, or **Enterprise** plan. The market must also be inside your plan's [data window](https://docs.polyhistorical.com/guides/pricing.md).

Files are created after a market ends, usually within a day. For a market that is still running or has only just ended, use [Get Snapshots](https://docs.polyhistorical.com/api-reference/get-snapshots.md).

## Request

```
https://api.polyhistorical.com/v1/markets/{slug}/snapshots/download
```

### Headers

**X-API-Key** `string` *required*

Your API key. See [Authentication](https://docs.polyhistorical.com/api-reference/overview.md#authentication).

### Path parameters

**slug** `string` *required*

The market slug, e.g. `btc-updown-5m-1788140100`

## Response

**market** `object`

The market object (same as [Get Market](https://docs.polyhistorical.com/api-reference/get-market.md))

**format** `string`

File format. Always `parquet`.

**url** `string`

Download link for the file. It works without your API key and expires at `expires_at`. The file downloads as `{slug}.parquet`.

**expires\_at** `string`

When the link stops working (ISO 8601)

**expires\_in** `integer`

Seconds until the link expires (currently 600, i.e. 10 minutes)

**size\_bytes** `integer`

File size in bytes

**sha256** `string`

SHA-256 checksum of the file (hex), for verifying the download

**row\_count** `integer`

Number of snapshots in the file

## Examples

### Get the link and download the file

```bash cURL theme={null}
curl -s -H "X-API-Key: YOUR_API_KEY" \
  "https://api.polyhistorical.com/v1/markets/btc-updown-5m-1788140100/snapshots/download" \
  | python3 -c "import sys, json; print(json.load(sys.stdin)['url'])" \
  | xargs curl -s -o btc-updown-5m-1788140100.parquet
```

```python Python theme={null}
import hashlib
import requests

slug = "btc-updown-5m-1788140100"
info = requests.get(
    f"https://api.polyhistorical.com/v1/markets/{slug}/snapshots/download",
    headers={"X-API-Key": API_KEY},
).json()

# The link is pre-authorized: don't send your API key to it
data = requests.get(info["url"]).content
assert hashlib.sha256(data).hexdigest() == info["sha256"]

with open(f"{slug}.parquet", "wb") as f:
    f.write(data)
```

### Response

```json theme={null}
{
  "market": {
    "slug": "btc-updown-5m-1788140100",
    "winner": "Up",
    "market_type": "5m",
    "start_time": "2026-08-31T01:35:00Z",
    "end_time": "2026-08-31T01:40:00Z",
    "coin_price_start": 77701.92547161,
    "coin_price_end": 77844.44,
    ...
  },
  "format": "parquet",
  "url": "https://hel1.your-objectstorage.com/polyhistorical/snapshots/v1/coin=btc/type=5m/date=2026-08-31/btc-updown-5m-1788140100.parquet?X-Amz-Algorithm=AWS4-HMAC-SHA256&X-Amz-Expires=600&X-Amz-Signature=...",
  "expires_at": "2026-11-01T10:10:00Z",
  "expires_in": 600,
  "size_bytes": 178278,
  "sha256": "3b1f0c6e2a...",
  "row_count": 2630
}
```

> [!NOTE]
>
> `market` is truncated here; it has all the fields from [Get Market](https://docs.polyhistorical.com/api-reference/get-market.md). Treat `url` as an opaque link: its host and format can change.

> [!TIP]
>
> Request the link right before you download. If it has expired, call this endpoint again for a fresh one. Downloading the file itself doesn't count against your [rate limit](https://docs.polyhistorical.com/guides/rate-limits.md).

## Errors

| Code | HTTP Status | When |
| - | - | - |
| `BAD_REQUEST` | 400 | The slug isn't a BTC, ETH, or SOL market |
| `UNAUTHORIZED` | 401 | Missing or invalid API key |
| `TIER_ACCESS_DENIED` | 403 | Your plan doesn't include downloads |
| `EXTENDED_DATA_ACCESS_REQUIRED` | 403 | The market is older than your Pro data window; a longer window gives access |
| `DATA_ACCESS_WINDOW_EXCEEDED` | 403 | The market is outside your plan's data window |
| `RESOURCE_NOT_FOUND` | 404 | No market with this slug |
| `ARCHIVE_NOT_AVAILABLE` | 404 | The market's file isn't ready yet (or the market has no snapshots). Use [Get Snapshots](https://docs.polyhistorical.com/api-reference/get-snapshots.md) meanwhile. |
| `ARCHIVE_UNAVAILABLE` | 503 | Downloads are temporarily unavailable. Retry later. |

See [Error Handling](https://docs.polyhistorical.com/guides/errors.md) for the error response format.


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