Docs
Flowseeker/API Reference/Flow

Raw flow feed for a ticker (Flow Score + FlowBonus per trade)

GEThttps://api.skylit.ai/v1/flow/{ticker}

Returns the most recent options trades for {ticker} within the requested timeframe, each scored on Skylit's directional Flow Score (-100 → +100) and conviction-weighted FlowBonus. The response also includes timeframe-level VWF / SDF / FIR aggregates.

Paging. Trades come newest first. When a page is full (limit rows read), meta.nextCursor is set: pass it back as cursor with the same filters to get the next, older page. It resumes exactly after the last row, so no trade is skipped or repeated, even when several share one nanosecond timestamp. No nextCursor means you have reached the start of the window; a cursor page with no trades returns 200 with an empty trades array. min_flow_score, min_flow_bonus and min_rvol filter after the read, so a page can hold fewer than limit trades while nextCursor is still set: keep following it. meta.nextEndTime is the last row's exact time (nanoseconds) for clients that page with end_time; it is inclusive, so trades at that instant can repeat. Prefer cursor.

Backfilling a day for one contract, 500 trades per request:

GET /v1/flow/SPY?date=2026-09-30&expiration=2026-09-30&min_strike=660&max_strike=660&option_type=call&limit=500
→ meta.nextCursor = "dDEuMTc5..."
GET /v1/flow/SPY?date=2026-09-30&expiration=2026-09-30&min_strike=660&max_strike=660&option_type=call&limit=500&cursor=dDEuMTc5...
→ repeat until meta.nextCursor is absent

Each page costs one request. Splitting the window around the 500-row limit instead (bisecting) re-reads overlapping ranges, spends the account's query budget several times over, and gets an X-Skylit-Hint response header pointing here.

Authorization

Authorization: Bearer <your API key>

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

Path parameters

  • tickerstringrequired

    Underlying ticker symbol (uppercase, e.g. SPY, AAPL).

Query parameters

  • timeframestringdefault 1h

    Trailing window label for the request. Supported values: 5m, 15m, 1h, 4h, 1d.

    5m15m1h4h1d
  • limitintegerdefault 100min 1 · max 500

    Max trades returned. Server caps this at 500.

  • cursorstring

    meta.nextCursor from the previous page, passed back unchanged with the same filters. Opaque; an invalid value returns 400.

  • min_premiumnumberdouble

    Minimum total premium per trade (USD).

  • option_typestringdefault all

    Filter to calls or puts. all returns both.

    callputall
  • trade_typestringdefault all

    Filter by trade type. Comma-separated for multiple; every token must be one of the listed values.

    sweepmulti_legall
  • moneynessstringdefault all

    Moneyness category filter. Comma-separated for multiple (e.g. otm,deep_otm). Every token must be one of the listed values; an unknown token returns 400.

    deep_itmitmatmotmdeep_otmall
  • start_timestring

    Optional lower bound for the trade window. Accepts RFC 3339 (2026-05-27T13:30:00Z) or Unix seconds. Omit to use the timeframe.

  • end_timestring

    Optional upper bound (RFC 3339 or Unix seconds).

  • max_premiumnumberdouble

    Maximum total premium per trade (USD).

  • min_contractsintegermin 0

    Minimum contract size per trade.

  • max_contractsintegermin 0

    Maximum contract size per trade.

  • single_leg_onlybooleandefault false

    If true, exclude trades flagged as part of a multi-leg structure.

  • min_dteinteger

    Minimum days to expiration.

  • max_dteinteger

    Maximum days to expiration.

  • min_strikenumberdouble

    Minimum strike price (inclusive).

  • max_strikenumberdouble

    Maximum strike price (inclusive).

  • expirationstringdate

    Filter to a single expiration date (YYYY-MM-DD).

  • conviction_weightsstring

    Optional JSON object overriding the Flow Score conviction weights. Weights must be non-negative and sum to within 0.95–1.05, else 400.

  • min_flow_scoreintegermin -100 · max 100

    Filter to trades with flowScore ≥ this value (-100..100).

  • min_flow_bonusintegermin 0

    Filter to trades with flowBonus ≥ this value.

  • min_rvolnumberdoublemin 0

    Filter to trades with relative volume ≥ this multiple.

  • include_clustersbooleandefault true

    If true, attach cluster* fields when a trade is part of a multi-leg cluster (sweep, condor, etc.).

  • datestringdate

    Trading date (YYYY-MM-DD). Defaults to current trading date.

Responses

  • 200

    Flow feed for {ticker}.

  • 400

    Request validation failed.

  • 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 key exceeded its requests-per-minute limit (X-RateLimit-Limit; no Retry-After, wait until X-RateLimit-Reset), or the account is over one of the API's own limits, such as the query budget (queries running at once, fresh queries per second): TOO_MANY_CONCURRENT_QUERIES or RATE_LIMITED with Retry-After. Not charged; retry after the wait.

  • 500

    Unexpected server error (INTERNAL_ERROR, DATABASE_ERROR). Not charged; safe to retry with exponential backoff.

  • 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

  • dataobjectrequired
    • tickerstringrequired
    • timeframestringrequired
    • tradesobject[]required
    • aggregateobjectrequired

      Window-level scoring components.

    • tradeCountintegerrequired
    • sweepCountintegerrequired
    • totalPremiumnumberrequired
    • queryTimeMsintegerrequired
  • metaobjectrequired
    • timestampstringdate-timerequired

      Server-side timestamp the response was generated at.

    • requestIdstringrequired

      Short opaque ID for log correlation.

    • nextCursorstring

      Trade feeds (/v1/flow/{ticker}, /v1/contract/{symbol}/trades): pass back as cursor with the same filters for the next page. Present only when more rows may follow.

    • nextEndTimestringdate-time

      /v1/flow/{ticker} only: the last row's exact time (RFC 3339 with nanoseconds), for end_time paging. Inclusive, so rows at that instant can repeat; nextCursor never repeats or skips.

Last updated

Was this page helpful?