---
title: "Live per-strike heatmap (one or more symbols)"
method: GET
path: "/v1/heatmap"
tags: ["Heatmap"]
---

# Live per-strike heatmap (one or more symbols)

`GET /v1/heatmap`

## Request

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

Current per-strike heatmap for one or more symbols at the latest
snapshot. Includes the live `velocityPct` per strike. Pass multiple
comma-separated symbols for a single cross-asset call (the app's
Trinity is `SPXW,SPY,QQQ`; `SPX` is the monthlies only), and
`expirations` to net each strike over specific expiration dates instead
of the nearest `maxExpirations`. A call that cannot finish within 20
seconds answers `504` `gateway_timeout` (refunded); retry, or request
fewer symbols.

## Query parameters

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

## Response `200`

Live 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`: 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.
- `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)