Docs
Heatseeker/API Reference/Heatmap

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

GEThttps://api.skylit.ai/v1/historical/range

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.

Authorization

Authorization: Bearer <your API key>

Required. A missing header returns 401; an invalid, revoked or expired key returns 403.

Query parameters

  • symbolsstringrequired

    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. At most 10 distinct symbols (more → 400 invalid_parameter). Unknown symbols in a list are omitted; if none is available → 404 symbol_not_found.

  • fromstringdate-timerequired

    RFC3339 start of the window (inclusive). Up to 365 days back.

  • tostringdate-timerequired

    RFC3339 end of the window (inclusive). At most 15 minutes after from, not in the future.

  • metricstringdefault gamma

    Which Greek exposure to return per strike.

    gammavanna
  • maxStrikesdefault 92

    Maximum number of strikes around spot to return: an integer from 1 to 1000, or all for every strike the snapshot lists (SPXW lists about 730). Values above 1000 return 400 invalid_parameter; they are never silently reduced. Values below 1 are treated as 1. The single-symbol stream (/v1/stream?symbol=) accepts at most 400 and no all.

  • maxExpirationsdefault 5

    How many of the nearest expirations to net into each strike's value: an integer from 1 to 60, or all. Values above 60 return 400 invalid_parameter. Ignored when expirations is set.

  • expirationsstring

    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.

Responses

  • 200

    Every snapshot in the window, per symbol.

  • 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.

Response fields

  • dataobjectrequired
    • fromstringdate-timerequired
    • tostringdate-timerequired
    • symbolsobject[]required
  • metaobjectrequired
    • metricstringrequired
      gammavanna
    • resolutionstringrequired

      Time resolution of the data served: "1s" when every symbol came from 1-second data, "1m" when any came from minute-resolution history.

      1s1m
    • modestringrequired
      livehistorical
    • cachedbooleanrequired

      True if served from the in-process cache.

Last updated

Was this page helpful?