---
title: "Live SSE stream (one symbol per connection)"
method: GET
path: "/v1/stream"
tags: ["Heatmap"]
---

# Live SSE stream (one symbol per connection)

`GET /v1/stream`

A **Server-Sent Events** (`text/event-stream`) feed of live per-strike
heatmap updates for **one** symbol. Open one connection per symbol.

**Events:**
- `connected` — handshake, payload `{symbol, creditsRemaining}`.
- `initial_data` — current heatmap snapshot on connect.
- `snapshot_update` — full heatmap on each change.
- `velocity_update` — per-strike % change.
- `credits` — emitted every minute boundary, payload `{remaining}`.
- `closed` — stream terminates with `{reason: "insufficient_credits"
  | "account_suspended" | "credit_check_failed"}`.
- `reconnect` — server is recycling the connection (after ~1h),
  payload `{reason: "max_duration"}`. Reconnect to continue.
- `: keepalive` comment every 30s for proxy keepalive.

**Pricing.** 1 credit on connect (charged before the SSE upgrade —
an under-funded client gets a clean `402` HTTP response, not a
half-open stream), then 1 credit per minute open. The per-minute
ticker emits `event: credits {remaining: N}` after each successful
debit so clients can budget the next minute.

**Concurrency.** Up to 5 concurrent streams per customer per pod.
Exceeding the cap returns `429` `stream_limit_reached`.

> OpenAPI is request/response-oriented and can't fully model an event
> stream. See [docs/api-credits.md](https://github.com/SkylitAI/skylit-main/blob/main/docs/api-credits.md#live-stream-v1stream)
> for the full stream lifecycle.

## Query parameters

- `symbol` string, required
- `metric` 'gamma' | 'vanna'
- `maxStrikes` integer

## Response `200`

An SSE stream of heatmap events.

## Other responses

- `400` — Request validation failed.
- `401` — Missing or invalid API key.
- `403` — API key revoked/expired, monthly quota exceeded, or the account's API access is suspended (`account_suspended`).
- `404` — Unknown resource (ticker / sector / window with no data).
- `429` — Per-minute rate limit exceeded.

---

[API](https://skmtc.net/skylit/apis/flowseeker-skylit-public-api.md) · [All operations](https://skmtc.net/skylit/apis/flowseeker-skylit-public-api/llms.txt) · [OpenAPI document](https://skmtc-service-staging.skmtc.workers.dev/v1/apis/skylit/flowseeker-skylit-public-api/revisions/3280190b1b24/schema)