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

# Download

> Get bulk download URLs for a UTC date.

Use `GET /download` to request a daily bulk manifest with `source`, `market`, and `date` and get all snapshot download URLs for that UTC date in one response.

Open datasets do not require an `Authorization` header. Bearer auth or machine payment is only required when the dataset access policy for the requested data requires it.

## Endpoint

`GET /download`

## Preferred workflow

1. Use [Catalog](/reference/catalog) to confirm the exact `source` and `market`.
2. Request `GET /download?source=...&market=...&date=...`.
3. Read the manifest and download the returned snapshot URLs.
4. Decompress each `.jsonl.zst` file locally and treat it as the canonical normalized event source.

## Parameters

Required query params: `source`, `market`, `date`

<ParamField query="source" type="string">
  Source ID for the bulk manifest request.
</ParamField>

<ParamField query="market" type="string">
  Exact Polaris market ID for the bulk manifest request.
</ParamField>

<ParamField query="date" type="string">
  UTC date for the bulk manifest request, in strict `YYYY-MM-DD` format.
</ParamField>

## Bulk manifest behavior

When you request `source`, `market`, and `date`, Polaris returns a JSON manifest for that UTC date.

* The endpoint uses canonical query params only. Use `source` and `market`, not legacy aliases such as `exchange` or `asset`.
* The date must be `YYYY-MM-DD`.
* The endpoint returns JSON. It does not redirect to a single file.
* Polaris groups available files by timestamp and returns one manifest entry per snapshot timestamp.
* If a timestamp already has one standardized object, the returned URL points to that object directly.
* If a timestamp has multiple standardized shards, Polaris assembles them into one temporary file before returning the URL.
* If no standardized object exists for a timestamp, Polaris builds a standardized snapshot from the available source files and returns a URL for that assembled output.

Polaris first looks for standardized objects under `standard/{source}/{market}/{date}/`. If none exist for the day, it falls back to the available raw source objects for that date.

## Bulk manifest response fields

<ResponseField name="source" type="string" required>
  Source you queried.
</ResponseField>

<ResponseField name="market" type="string" required>
  Market you queried.
</ResponseField>

<ResponseField name="date" type="string" required>
  UTC date you queried, in `YYYY-MM-DD` format.
</ResponseField>

<ResponseField name="total" type="number" required>
  Number of snapshot entries returned for that date.
</ResponseField>

<ResponseField name="total_bytes" type="number" required>
  Total size in bytes across the returned snapshot files.
</ResponseField>

<ResponseField name="snapshots" type="object[]" required>
  Snapshot download entries for the requested date.
</ResponseField>

<ResponseField name="snapshots.date" type="string" required>
  UTC date covered by the snapshot, in `YYYY-MM-DD` format.
</ResponseField>

<ResponseField name="snapshots.timestamp" type="string" required>
  UTC timestamp within the date, formatted as `HHMMSS`.
</ResponseField>

<ResponseField name="snapshots.key" type="string" required>
  Opaque snapshot identifier for that timestamp.
</ResponseField>

<ResponseField name="snapshots.url" type="string" required>
  Pre-signed download URL for the standardized snapshot file.
</ResponseField>

<ResponseField name="snapshots.expires_in_seconds" type="number" required>
  Lifetime of the pre-signed download URL, typically `86400` (24 hours).
</ResponseField>

## Bulk manifest example

```bash theme={null}
curl "https://api.polaris.supply/download?source=hyperliquid&market=BTC&date=2026-07-10"
```

```json theme={null}
{
  "source": "hyperliquid",
  "market": "BTC",
  "date": "2026-07-10",
  "total": 24,
  "total_bytes": 123456789,
  "snapshots": [
    {
      "date": "2026-07-10",
      "timestamp": "120000",
      "key": "standard-hyperliquid-BTC-2026-07-10-120000",
      "url": "https://storage.polaris.supply/...",
      "expires_in_seconds": 86400
    }
  ]
}
```

## Access behavior

* Open datasets do not require bearer auth.
* Preview or restricted datasets may require bearer auth or a machine payment challenge, depending on dataset policy.
* Bulk manifest access is evaluated against the requested dataset and date.

## Error behavior

* `400` for missing required params or an invalid `date`
* `401` when bearer auth is required by dataset policy
* `402` when the dataset requires payment and no auth or payment is provided
* `404` when no matching snapshot data is found

## Next steps

* Read [Catalog](/reference/catalog) to confirm valid `source` and `market` values.
* Read [Snapshots](/reference/snapshots) if you want to inspect available files before requesting a bulk manifest.