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

Live only

The stream carries trades that arrive after you connect; it replays no history. Load a backlog from /v1/flow/{ticker} first if you need one, then attach here. limit is rejected with 400 rather than silently ignored.

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

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

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

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.

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