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

`GET https://api.skylit.ai/v1/heatmap`

API: Heatseeker. Credits: 1.

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 (Trinity) call, and
`expirations` to net each strike over specific expiration dates instead
of the nearest `maxExpirations`.

## Authentication

Send your Skylit API key as a bearer token: `Authorization: Bearer <key>`. No other header is accepted.

## Parameters

| Name | In | Type | Required | Description |
| --- | --- | --- | --- | --- |
| `symbols` | query | string | yes | One ticker, or a comma-separated list for a single cross-asset call (e.g. `SPY` or `SPY,SPX,QQQ`). Each is returned as an element of `data.symbols`. |
| `metric` | query | string | no | Which Greek exposure to return per strike. (one of `gamma`, `vanna`; default `gamma`) |
| `maxStrikes` | query | integer | no | Maximum number of strikes around spot to return. (default `92`; min 1; max 400) |
| `maxExpirations` | query | integer | no | How many of the nearest expirations to net into each strike's `value`. Ignored when `expirations` is set. (default `5`; min 1; max 60) |
| `expirations` | query | string | no | Net each strike over exactly these expirations (`YYYY-MM-DD`, comma-separated) — one for a single-expiration heatmap (`2026-05-22`) or several for a custom set (`2026-05-22,2026-06-19`). Supersedes `maxExpirations`, and reaches any expiration the snapshot has, not just the nearest ones. Requested dates the symbol does not have are ignored; the `expirations` array in the response lists what was actually used. If none of them match, the response is `404` with `code: expiration_not_found` and the available dates in the message. On `/v1/heatmap`, expirations that have already expired are not available (they are trimmed from the live snapshot) — replay them with `/v1/historical` instead. |
| `layout` | query | string | no | `net` (default) returns one net value per strike. `matrix` also returns `matrix`, the per-expiration grid those values are summed from. (one of `net`, `matrix`; default `net`) |

## Example request

```bash
curl "https://api.skylit.ai/v1/heatmap?symbols=SPY,SPX,QQQ" \
  -H "Authorization: Bearer $SKYLIT_API_KEY"
```

## Responses

### 200

Live heatmap snapshot(s).

Headers: `Cache-Control`, `X-RateLimit-Limit`, `X-RateLimit-Remaining`, `X-RateLimit-Reset`.

SPY live (truncated):

```json
{
  "data": {
    "symbols": [
      {
        "symbol": "SPY",
        "asOf": "2026-05-22T14:31:00Z",
        "spot": 591.23,
        "previousClose": 589.1,
        "priceChange": 2.13,
        "priceChangePercent": 0.36,
        "expirations": [
          "2026-05-22",
          "2026-05-23",
          "2026-05-30"
        ],
        "strikes": [
          {
            "strike": 590,
            "value": 1894300.4,
            "nodeType": "king",
            "velocityPct": 12.4
          },
          {
            "strike": 595,
            "value": 642100.2,
            "nodeType": "gatekeeper",
            "velocityPct": -3.1
          },
          {
            "strike": 585,
            "value": 88010,
            "nodeType": "normal",
            "velocityPct": 0.4
          }
        ]
      }
    ]
  },
  "meta": {
    "metric": "gamma",
    "resolution": "1m",
    "mode": "live",
    "cached": false
  }
}
```

SPY netted over one expiration (`expirations=2026-05-23`):

```json
{
  "data": {
    "symbols": [
      {
        "symbol": "SPY",
        "asOf": "2026-05-22T14:31:00Z",
        "spot": 591.23,
        "previousClose": 589.1,
        "priceChange": 2.13,
        "priceChangePercent": 0.36,
        "expirations": [
          "2026-05-23"
        ],
        "strikes": [
          {
            "strike": 590,
            "value": 412880.1,
            "nodeType": "king",
            "velocityPct": 8.2
          },
          {
            "strike": 595,
            "value": 121400.7,
            "nodeType": "gatekeeper",
            "velocityPct": -1.4
          }
        ]
      }
    ]
  },
  "meta": {
    "metric": "gamma",
    "resolution": "1m",
    "mode": "live",
    "cached": false
  }
}
```

### 400

Request validation failed.

### 401

Missing or invalid API key.

### 403

The API key is invalid, revoked or expired, or the account is 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.

Headers: `Retry-After`.

### 503

Heatmap data is temporarily unavailable.