Live cross-ticker options flow (Server-Sent Events)
https://api.skylit.ai/v1/flow/streamA long-lived text/event-stream carrying options trades as they
print, across every ticker unless you filter. This is the same feed
that drives the Skylit website, with the same filter semantics.
Resuming without gaps
A new connection carries trades that arrive after you connect.
To pick up where a previous connection stopped, reconnect with the
last trade_id you received, either as the Last-Event-ID header
(browsers' EventSource sends it automatically) or as since=. The
stream first sends the trades you missed, through your filters, then
a replayed event, then live trades.
- The replay starts 10 seconds before your cursor, because
trades arrive in roughly, not strictly, timestamp order. Drop any
trade_idyou already hold. - It reaches back at most 15 minutes. Anything older, or a replay
that could not be served, arrives as a
gapevent naming the window; fetch it from/v1/flow/{ticker}. - Replayed trades carry the same
trade_idand fields as live ones; their percentile-style scores use current baselines. - Cancelled prints are not replayed.
limit is rejected with 400: the stream is not a history endpoint.
Load a backlog from /v1/flow/{ticker} first if you need one.
Pricing
Costs differ from one-shot routes because they accrue over time:
- 1 credit on connect, charged before the stream opens — an
under-funded client gets a clean
402, not a stream that dies immediately. - 1 credit per minute open, reported back as a
creditsevent. - 5 concurrent streams per account; a sixth gets
429. - 1 hour maximum, then a
reconnectevent and a clean close.
Filter names
This endpoint uses the live-feed filter vocabulary, which differs
from the curated parameters on /v1/flow/{ticker}: use
show_calls/show_puts rather than option_type, and
min_size/max_size rather than min_contracts/max_contracts.
Events
| Event | Payload | Meaning |
|---|---|---|
connected | stream terms | First frame after the stream opens. |
trade | trade object | A trade that passed your filters. Flags sweep_trade, multi_leg and cross_trade are always present. The SSE id: is the trade's trade_id. |
replayed | {"count": N, "from_ns": "...", "to_ns": "..."} | Resume only. The catch-up is complete; live trades follow. |
gap | {"from_ns": "...", "to_ns": "...", "reason": "..."} | Resume only. Trades in this window were not replayed: beyond_lookback, replay_limit or replay_unavailable. |
credits | {"remaining": N} | Emitted each minute after billing. |
lagged | {"dropped": N} | You read slower than the tape; trades were skipped. |
closed | {"reason": "..."} | Terminal. insufficient_credits, account_suspended, credit_check_failed, or feed_unavailable. |
reconnect | {"reason": "max_duration"} | Terminal after 1h; reconnect to continue. |
A : comment arrives every 30s as a proxy keepalive. Treat a stalled
stream as a reconnect signal.
Matching trades to /v1/flow/{ticker}
Each trade carries these fields with the same values as the REST
trade, so the two feeds can be joined exactly:
| Stream field | REST field | Notes |
|---|---|---|
trade_id | tradeId | Stable; the same print always has the same id. |
ts_event_ns | timestampNs | Nanoseconds since the epoch, as a string. ts_event stays in milliseconds. |
moneyness_category | moneyness | DEEP_ITM, ITM, ATM, OTM, DEEP_OTM. The stream's own moneyness is the simple side-of-spot label (ITM/ATM/OTM). |
liquidity_grade | liquidityGrade | null when either side of the quote is missing. |
Prints of one contract often share a millisecond, so match on
trade_id (or ts_event_ns plus raw_symbol), not on ts_event.
A missing quote is null on both feeds.
Example
curl -N -H "Authorization: Bearer $SKYLIT_API_KEY" \
"https://flow-api.skylit.ai/v1/flow/stream?min_premium=100000&show_puts=false"
-N matters: without it curl buffers the response and the stream
appears to hang.
Authorization
Authorization: Bearer <your API key>Required. A missing header returns 401; an invalid, revoked or expired key returns 403.
Query parameters
sincestringResume cursor for clients that cannot set
Last-Event-ID: atrade_id, a nanosecond timestamp, or an RFC 3339 time. An unparseable value is rejected with400 invalid_cursor.tickerstringComma-separated tickers to include (e.g.
AAPL,NVDA, max 50). Omit to stream every ticker.exclude_tickerstringComma-separated tickers to exclude.
min_premiumnumberdoubleMinimum premium per trade (USD). Strongly recommended — an unfiltered stream carries the entire tape.
max_premiumnumberdoubleMaximum premium per trade (USD).
min_sizeintegermin 0Minimum contracts per trade.
max_sizeintegermin 0Maximum contracts per trade.
show_callsbooleandefaulttrueInclude calls.
show_putsbooleandefaulttrueInclude puts.
show_below_bidbooleandefaulttrueInclude prints below the bid. The five side toggles are independent buckets:
show_bidcovers exact-bid prints,show_askexact-ask, and the aggressive variants are gated by their own toggles.show_bidbooleandefaulttrueInclude prints at the bid.
show_midbooleandefaulttrueInclude prints at the mid.
show_askbooleandefaulttrueInclude prints at the ask.
show_above_askbooleandefaulttrueInclude prints above the ask.
min_dteintegerMinimum days to expiration.
max_dteintegerMaximum days to expiration.
only_0dtebooleandefaultfalseRestrict to contracts expiring today.
min_oiintegermin 0Minimum open interest on the contract.
max_oiintegermin 0Maximum open interest on the contract.
min_vol_oinumberdoubleMinimum volume/open-interest ratio.
max_vol_oinumberdoubleMaximum volume/open-interest ratio.
min_ivnumberdoubleMinimum implied volatility (decimal, e.g.
0.42).max_ivnumberdoubleMaximum implied volatility (decimal).
only_sweepsbooleandefaultfalseRestrict to multi-exchange sweeps.
only_crossesbooleandefaultfalseRestrict to pre-negotiated crosses. These carry no aggressor information, so
sideis not meaningful on them.only_multi_legbooleandefaultfalseRestrict to legs of multi-leg strategies.
exclude_multi_legbooleandefaultfalseExclude multi-leg legs, leaving outright trades.
min_flow_scoreintegermin -100 · max 100Minimum directional Flow Score (-100 → +100).
max_flow_scoreintegermin -100 · max 100Maximum directional Flow Score.
abs_min_flow_scoreintegermin 0 · max 100Minimum absolute Flow Score — conviction in either direction.
min_percentileintegerMinimum premium percentile for the ticker. Trades with no computed percentile are excluded once this is set.
05075909599show_stocksbooleandefaulttrueInclude single-stock underlyings.
show_etfbooleandefaulttrueInclude ETF underlyings.
show_indicesbooleandefaulttrueInclude index underlyings.
Headers
Last-Event-IDstringResume cursor: the last
trade_idreceived. Sent automatically byEventSourceon reconnect. Takes precedence oversince.
Responses
- 200
An open SSE stream. Frames are newline-delimited
event:/data:pairs as described above. - 400
An unsupported parameter was supplied —
limitis not valid on the stream (unsupported_parameter) — or the resume cursor could not be parsed (invalid_cursor). - 401
Missing or invalid API key.
- 402
The account's shared Skylit credit balance is lower than this route's cost. Top up to continue. Carries
X-Credits-Remaining: 0. - 403
Unknown, revoked or expired API key (the gateway's
forbidden), the account's API access is suspended (account_suspended) or blocked (account_blocked). Not retryable. - 404
Unknown ticker or contract (
SYMBOL_NOT_FOUND), or no data for the requested window. Not charged. - 429
Either the account's request rate limit, or its cap of 5 concurrent streams (
stream_limit_reached). - 503
Underlying data source temporarily unavailable, the credit balance could not be verified (
credit_check_failed), or the API is paused for maintenance (api_paused, with aRetry-Afterheader and aretry_afterfield in seconds). Not charged; safe to retry. - 504
The request did not complete within 25 seconds. Not charged; narrow the window or retry.
Response fields
Returns string.
Last updated