---
title: "Replay — every snapshot in a window (up to 15 minutes, 5 symbols)"
method: GET
path: "/v1/historical/range"
tags: ["Heatmap"]
---

# Replay — every snapshot in a window (up to 15 minutes, 5 symbols)

`GET /v1/historical/range`

## Request

- Base URL: `https://api.skylit.ai`
- URL: `https://api.skylit.ai/v1/historical/range`
- Auth: HTTP bearer

Every snapshot between `from` and `to` (inclusive) for up to 5
symbols, at the stored resolution — one per second where 1-second
history exists (`meta.resolution: "1s"`), otherwise one per minute.
Each frame's `values[i]` is the net exposure at
`axes[frame.axis].strikes[i]`, summed over that axis's expirations —
the same number `/v1/historical` reports as `strikes[i].value` for
that instant. Axes are listed once and referenced by id; a new axis
appears only when the visible strikes or expirations change (the
strike window follows spot). Plain JSON numbers; responses are
gzip-compressed when the request sends `Accept-Encoding: gzip`.

**Cost:** 25 credits per call.

## Query parameters

- `symbols` string, required
- `from` string, date-time, required
- `to` string, date-time, required
- `metric` 'gamma' | 'vanna'
- `maxStrikes` union
  - integer
  - 'all'
- `maxExpirations` union
  - integer
  - 'all'
- `expirations` string

## Response `200`

Every snapshot in the window, per symbol.

- object
  - `data` object, required
    - `from` string, date-time, required
    - `symbols` SymbolRange[], required
      - `axes` object[], required: Strike/expiration axes referenced by `frames[].axis`.
        - `expirations` string[], required: Expirations (YYYY-MM-DD) netted into each value.
        - `id` integer, required
        - `strikes` number[], required: Visible strikes, ascending.
      - `frames` object[], required: Snapshots in the window, oldest first.
        - `asOf` string, date-time, required: Snapshot instant (millisecond precision).
        - `axis` integer, required: Id of the axis in `axes` these values are aligned to.
        - `previousClose` number, required
        - `spot` number, required
        - `values` number[], required: Net exposure per strike, aligned with the axis's `strikes`.
      - `symbol` string, required: Canonical ticker for the returned data.
    - `to` string, date-time, required
  - `meta` Meta, required
    - `attribution` Attribution: Whether and how this response's data may be published. See `/legal/api#sharing`. An Agent or MCP client should never publish data where `shareable` is false, regardless of `shareClass`. `required`, `license`, `shareable` and `shareClass` are always sent on `/v1/options/*` and absent from the short form.
      - `license` 'personal' | 'commercial' | 'connected_app'
      - `required` boolean
      - `shareClass` 'derived' | 'derived_levels_only' | 'raw': "raw" (e.g. option quotes, greeks) must never be auto-published.
      - `shareable` boolean
      - `terms` string, uri
      - `text` string, required
      - `url` string, uri, required
    - `cached` boolean, required: True if served from the in-process cache.
    - `delayMinutes` integer: The delay applied when `delayed` is true.
    - `delayed` boolean: True when your plan's data is delayed and this latest-data request was served as of `delayMinutes` ago (mode is then `historical`). Absent on real-time plans.
    - `metric` 'gamma' | 'vanna', required
    - `mode` 'live' | 'historical', required
    - `resolution` '1s' | '1m', required: Time resolution of the data served: "1s" when every symbol came from 1-second data, "1m" when any came from minute-resolution history.

## Other responses

- `400`: Request validation failed.
- `401`: Missing API key (`unauthorized`), sent by the gateway.
- `403`: Unknown, revoked or expired key (`forbidden`, from the gateway), or an admin-suspended account (`account_suspended`).
- `404`: Unknown symbol, no data available, or none of the requested `expirations` exist for the symbol (`code: expiration_not_found`).
- `429`: Per-minute rate limit exceeded.
- `503`: Heatmap data is temporarily unavailable.

---

[API](https://skmtc.dev/skylit/apis/skylit-public-api.md) · [All operations](https://skmtc.dev/skylit/apis/skylit-public-api/llms.txt) · [OpenAPI document](https://skmtc.dev/skylit/apis/skylit-public-api/revisions/890b0ea4e6f5?raw)