Flowseeker/API Reference/Flow

Live cross-ticker options flow (Server-Sent Events)

GEThttps://api.skylit.ai/v1/flow/stream

A 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_id you already hold.
  • It reaches back at most 15 minutes. Anything older, or a replay that could not be served, arrives as a gap event naming the window; fetch it from /v1/flow/{ticker}.
  • Replayed trades carry the same trade_id and 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 credits event.
  • 5 concurrent streams per account; a sixth gets 429.
  • 1 hour maximum, then a reconnect event 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

EventPayloadMeaning
connectedstream termsFirst frame after the stream opens.
tradetrade objectA 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 fieldREST fieldNotes
trade_idtradeIdStable; the same print always has the same id.
ts_event_nstimestampNsNanoseconds since the epoch, as a string. ts_event stays in milliseconds.
moneyness_categorymoneynessDEEP_ITM, ITM, ATM, OTM, DEEP_OTM. The stream's own moneyness is the simple side-of-spot label (ITM/ATM/OTM).
liquidity_gradeliquidityGradenull 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

  • sincestring

    Resume cursor for clients that cannot set Last-Event-ID: a trade_id, a nanosecond timestamp, or an RFC 3339 time. An unparseable value is rejected with 400 invalid_cursor.

  • tickerstring

    Comma-separated tickers to include (e.g. AAPL,NVDA, max 50). Omit to stream every ticker.

  • exclude_tickerstring

    Comma-separated tickers to exclude.

  • min_premiumnumberdouble

    Minimum premium per trade (USD). Strongly recommended — an unfiltered stream carries the entire tape.

  • max_premiumnumberdouble

    Maximum premium per trade (USD).

  • min_sizeintegermin 0

    Minimum contracts per trade.

  • max_sizeintegermin 0

    Maximum contracts per trade.

  • show_callsbooleandefault true

    Include calls.

  • show_putsbooleandefault true

    Include puts.

  • show_below_bidbooleandefault true

    Include prints below the bid. The five side toggles are independent buckets: show_bid covers exact-bid prints, show_ask exact-ask, and the aggressive variants are gated by their own toggles.

  • show_bidbooleandefault true

    Include prints at the bid.

  • show_midbooleandefault true

    Include prints at the mid.

  • show_askbooleandefault true

    Include prints at the ask.

  • show_above_askbooleandefault true

    Include prints above the ask.

  • min_dteinteger

    Minimum days to expiration.

  • max_dteinteger

    Maximum days to expiration.

  • only_0dtebooleandefault false

    Restrict to contracts expiring today.

  • min_oiintegermin 0

    Minimum open interest on the contract.

  • max_oiintegermin 0

    Maximum open interest on the contract.

  • min_vol_oinumberdouble

    Minimum volume/open-interest ratio.

  • max_vol_oinumberdouble

    Maximum volume/open-interest ratio.

  • min_ivnumberdouble

    Minimum implied volatility (decimal, e.g. 0.42).

  • max_ivnumberdouble

    Maximum implied volatility (decimal).

  • only_sweepsbooleandefault false

    Restrict to multi-exchange sweeps.

  • only_crossesbooleandefault false

    Restrict to pre-negotiated crosses. These carry no aggressor information, so side is not meaningful on them.

  • only_multi_legbooleandefault false

    Restrict to legs of multi-leg strategies.

  • exclude_multi_legbooleandefault false

    Exclude multi-leg legs, leaving outright trades.

  • min_flow_scoreintegermin -100 · max 100

    Minimum directional Flow Score (-100 → +100).

  • max_flow_scoreintegermin -100 · max 100

    Maximum directional Flow Score.

  • abs_min_flow_scoreintegermin 0 · max 100

    Minimum absolute Flow Score — conviction in either direction.

  • min_percentileinteger

    Minimum premium percentile for the ticker. Trades with no computed percentile are excluded once this is set.

    05075909599
  • show_stocksbooleandefault true

    Include single-stock underlyings.

  • show_etfbooleandefault true

    Include ETF underlyings.

  • show_indicesbooleandefault true

    Include index underlyings.

Headers

  • Last-Event-IDstring

    Resume cursor: the last trade_id received. Sent automatically by EventSource on reconnect. Takes precedence over since.

Responses

  • 200

    An open SSE stream. Frames are newline-delimited event:/data: pairs as described above.

  • 400

    An unsupported parameter was supplied — limit is 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 a Retry-After header and a retry_after field 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

Was this page helpful?