Snapshots

curl --request GET \
  --url https://api.polaris.supply/snapshots

{
  "source": "<string>",
  "market": "<string>",
  "access.status": "<string>",
  "access.public_cutoff_date": "<string>",
  "total": 123,
  "total_bytes": 123,
  "limit": 123,
  "has_more": true,
  "next_cursor": "<string>",
  "snapshots": [
    {}
  ],
  "snapshots.date": "<string>",
  "snapshots.hour": 123,
  "snapshots.key": "<string>"
}

GET

https://api.polaris.supply

snapshots

Snapshots

curl --request GET \
  --url https://api.polaris.supply/snapshots

{
  "source": "<string>",
  "market": "<string>",
  "access.status": "<string>",
  "access.public_cutoff_date": "<string>",
  "total": 123,
  "total_bytes": 123,
  "limit": 123,
  "has_more": true,
  "next_cursor": "<string>",
  "snapshots": [
    {}
  ],
  "snapshots.date": "<string>",
  "snapshots.hour": 123,
  "snapshots.key": "<string>"
}

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

Use Catalog to choose a valid source and market.
Call GET /snapshots to list hourly snapshot files.
Call Download with source, market, date, and mode=json to get all download URLs for a UTC date.
Use key-based download only when you want one specific file instead of the day manifest.
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

string

required

Source ID to query.

string

required

Exact Polaris market ID to query.

string

Inclusive UTC start time, typically in ISO 8601 format.

string

Exclusive UTC end time, typically in ISO 8601 format.

number

default:200

Number of snapshot entries to return. Maximum 1000.

string

Opaque pagination token from a previous response.

boolean

Set to true to list venue-native raw snapshot files instead of standardized hourly artifacts. Requires bearer auth with a paid subscription.

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.

Response fields

string

required

Source you queried.

string

required

Market you queried.

string

required

Dataset access state for the requested market. One of open, preview, or restricted.

string

Latest UTC date available without gated access when a public cutoff exists.

number

required

Number of snapshot entries in the response.

number

required

Total size in bytes across matching source files.

number

required

Effective page size applied to the response.

boolean

required

Whether another page of snapshot entries is available.

string

Opaque pagination token for the next page, when present.

object[]

required

Matching hourly snapshot entries.

string

required

UTC date covered by the hourly artifact, in YYYY-MM-DD format.

number

required

UTC hour covered by the artifact, 0–23.

string

required

Opaque snapshot identifier for single-file GET /download?key=... requests when you need one file at a time.

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

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:

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:

{
  "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 to fetch a bulk day manifest or a single snapshot file.
Read Trades and OHLCV if you plan to derive narrower views from normalized data.

Catalog Download

Getting Started

SDKs

Data Schemas

Reference

Resources

Snapshots

Preferred historical workflow

`GET /snapshots`

Parameters

Notes

Response fields

Raw snapshots

Python SDK

Error behavior

What to do with snapshot files

Next steps

​Preferred historical workflow

​GET /snapshots

​Parameters

​Notes

​Related schemas

​Response fields

​Raw snapshots

​Python SDK

​Error behavior

​What to do with snapshot files

​Next steps

Preferred historical workflow

`GET /snapshots`

Parameters

Notes

Related schemas

Response fields

Raw snapshots

Python SDK

Error behavior

What to do with snapshot files

Next steps