---
title: "Replay — per-strike heatmap at a past instant (one or more symbols)"
method: GET
path: "/v1/historical"
tags: ["Heatmap"]
---

# Replay — per-strike heatmap at a past instant (one or more symbols)

`GET /v1/historical`

## Request

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

The latest snapshot at or before `at` for one or more symbols — same
shape as `/v1/heatmap` minus `velocityPct` (velocity is live-only),
including `layout=matrix` for the per-expiration grid. Precision is
1 second where 1-second history exists for that day and 1 minute
otherwise; `meta.resolution` says which. `at` may go back to
2023-03-28, where heatmap history begins (coverage per symbol varies;
`/v1/symbols` lists each symbol's first date). If no snapshot exists
at/near that instant the response is `404` with `code: no_data`.
A read that cannot finish within 20 seconds answers `504`
`gateway_timeout` (refunded); retry, or request fewer symbols.

## Query parameters

- `symbols` string, required
- `at` string, date-time, required
- `metric` 'gamma' | 'vanna'
- `maxStrikes` union
  - integer
  - 'all'
- `maxExpirations` union
  - integer
  - 'all'
- `includeEmpty` boolean
- `expirations` string
- `layout` 'net' | 'matrix'

## Response `200`

Historical heatmap snapshot(s).

- object
  - `data` object, required
    - `symbols` SymbolHeatmap[], required
      - `asOf` string, date-time, required: RFC3339 timestamp of the snapshot actually returned (nearest to the requested instant).
      - `expirations` string[], required: Expiration dates (YYYY-MM-DD) contributing to each strike's net value.
      - `matrix` array[]: Present only with `layout=matrix`. One row per entry in `strikes`, one column per entry in `expirations`: `matrix[i][j]` is the exposure at strike i for expiration j.
        - number[]
      - `previousClose` number, required
      - `priceChange` number, required: The board's spot minus previous close (the board's spot, not `spot`, on `/v1/heatmap`).
      - `priceChangePercent` number, required
      - `spot` number, required: On `/v1/heatmap`, the latest underlying price at the time of the request, which can be newer than the board. On `/v1/historical` and in stream frames, the spot the board was computed at. The board's own spot is `previousClose + priceChange`.
      - `strikes` StrikeNode[], required: Per-strike nodes, ordered by strike ascending.
        - `nodeType` 'king' | 'gatekeeper' | 'pika' | 'barney' | 'significant' | 'normal', required: Skylit's node classification for this strike.
        - `strike` number, required: Strike price.
        - `value` number, required: Net exposure for the selected `metric` at this strike (summed across the returned expirations).
        - `velocityPct` number: Live percent change of this strike's value over the velocity window. Present on `/v1/heatmap` only; omitted on `/v1/historical`.
      - `symbol` string, required: Canonical ticker for the returned data.
  - `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.
- `402`: Out of credits (`insufficient_credits`).
- `403`: Unknown, revoked or expired key (`forbidden`, from the gateway), or an admin-suspended account (`account_suspended`).
- `404`: No snapshot at/near the requested instant, none of the requested symbols is available, or none of the requested `expirations` exist in that snapshot.
- `429`: Per-minute rate limit exceeded.
- `503`: Heatmap data is temporarily unavailable.
- `504`: The request did not finish in time (`gateway_timeout`). Refunded; retry, or narrow the request.

---

[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)