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

# Snapshots

> List canonical hourly snapshot files and plan bulk historical ingestion.

Snapshots are the canonical index for standardized historical data. Use them to inspect available hourly artifacts, estimate byte volume, and decide which dates you want to fetch through the bulk `GET /download` manifest flow.

`GET /snapshots` is a public listing endpoint. You do not need an `Authorization` header to browse available snapshot files. Add `raw=true` to list venue-native raw snapshot files instead — this requires paid auth.

## Preferred historical workflow

1. Use [Catalog](/reference/catalog) to choose a valid `source` and `market`.
2. Call `GET /snapshots` to list hourly snapshot files.
3. Call [Download](/reference/download) with `source`, `market`, `date`, and `mode=json` to get all download URLs for a UTC date.
4. Use `key`-based download only when you want one specific file instead of the day manifest.
5. Decompress each `.jsonl.zst` file locally and treat it as the canonical normalized event source.

## `GET /snapshots`

Public endpoint for standardized hourly snapshot artifacts in `.jsonl.zst`.

* Required: `source`, `market`
* Optional: `from`, `to`, `limit`, `cursor`, `raw`
* Default: `limit=200`
* Maximum: `limit=1000`
* If `from` and `to` are omitted, the server defaults to a recent 24-hour lookback ending at `now`

## Parameters

<ParamField query="source" type="string" required>
  Source ID to query.
</ParamField>

<ParamField query="market" type="string" required>
  Exact Polaris market ID to query.
</ParamField>

<ParamField query="from" type="string">
  Inclusive UTC start time, typically in ISO 8601 format.
</ParamField>

<ParamField query="to" type="string">
  Exclusive UTC end time, typically in ISO 8601 format.
</ParamField>

<ParamField query="limit" type="number" default={200}>
  Number of snapshot entries to return. Maximum `1000`.
</ParamField>

<ParamField query="cursor" type="string">
  Opaque pagination token from a previous response.
</ParamField>

<ParamField query="raw" type="boolean">
  Set to `true` to list venue-native raw snapshot files instead of standardized hourly artifacts. Requires bearer auth with a paid subscription.
</ParamField>

## Notes

* Standard listing is public and does not require bearer auth.
* Raw listing (`raw=true`) requires bearer auth with a paid subscription.
* Snapshot rows only appear for UTC hours that actually have source files behind them.
* The response includes dataset-level access metadata so you can distinguish open, preview, and restricted markets before you download.

## Related schemas

## Response fields

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

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

<ResponseField name="access.status" type="string" required>
  Dataset access state for the requested market. One of `open`, `preview`, or `restricted`.
</ResponseField>

<ResponseField name="access.public_cutoff_date" type="string">
  Latest UTC date available without gated access when a public cutoff exists.
</ResponseField>

<ResponseField name="total" type="number" required>
  Number of snapshot entries in the response.
</ResponseField>

<ResponseField name="total_bytes" type="number" required>
  Total size in bytes across matching source files.
</ResponseField>

<ResponseField name="limit" type="number" required>
  Effective page size applied to the response.
</ResponseField>

<ResponseField name="has_more" type="boolean" required>
  Whether another page of snapshot entries is available.
</ResponseField>

<ResponseField name="next_cursor" type="string">
  Opaque pagination token for the next page, when present.
</ResponseField>

<ResponseField name="snapshots" type="object[]" required>
  Matching hourly snapshot entries.
</ResponseField>

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

<ResponseField name="snapshots.hour" type="number" required>
  UTC hour covered by the artifact, `0`–`23`.
</ResponseField>

<ResponseField name="snapshots.key" type="string" required>
  Opaque snapshot identifier for single-file `GET /download?key=...` requests when you need one file at a time.
</ResponseField>

## Raw snapshots

Add `raw=true` to list venue-native raw snapshot files instead of standardized hourly artifacts. This is useful when you need:

* Replay venue messages for audits
* Maintain your own venue-specific normalization
* Access unmodified venue-native payloads

Raw snapshot listing requires bearer auth with a paid subscription. The response uses the same shape but entries contain `date` and `key` without an `hour` field.

## Python SDK

```python theme={null}
from datetime import datetime, timedelta, timezone

from polaris_data import PolarisClient

end = datetime.now(timezone.utc)
start = end - timedelta(hours=24)

with PolarisClient() as client:
    snapshots = client.list_snapshots(
        source="hyperliquid",
        market="BTC-USD",
        from_=start,
        to=end,
    )

for snapshot in snapshots[:2]:
    print(snapshot.key)
```

Example:

```bash theme={null}
curl "https://api.polaris.supply/snapshots?source=hyperliquid&market=BTC-USD&from=2026-05-07T00:00:00Z&to=2026-05-07T03:00:00Z&limit=2"
```

Response shape:

```json theme={null}
{
  "source": "hyperliquid",
  "market": "BTC-USD",
  "access": {
    "status": "preview",
    "public_cutoff_date": "2026-05-02"
  },
  "total": 2,
  "total_bytes": 987654321,
  "limit": 2,
  "has_more": false,
  "next_cursor": null,
  "snapshots": [
    {
      "date": "2026-05-07",
      "hour": 0,
      "key": "standard-hyperliquid-BTC-USD-2026-05-07-00"
    }
  ]
}
```

## Error behavior

* `400` for a missing or invalid parameter
* `401` when bearer auth is required for raw snapshot listing

## What to do with snapshot files

After download, decompress the `.jsonl.zst` file locally and use it as the canonical normalized event source. You can derive trade-only views, local OHLCV bars, and narrower event subsets without repeating the original API request.

## Next steps

* Read [Download](/reference/download) to fetch a bulk day manifest or a single snapshot file.
* Read [Trades](/sdks/trades) and [OHLCV](/sdks/ohlcv) if you plan to derive narrower views from normalized data.