Docs
Flowseeker/API Reference/Underlying

Raw enriched trades for a ticker

GEThttps://api.skylit.ai/v1/underlying/{ticker}/trades

Returns the raw enriched trade rows that feed the chart bars and the live feed. Supports rich filtering — sweep-only / multi-leg, moneyness, premium floor, DTE / strike / expiration windows. See OptionTradeRow below.

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

  • startstring

    Lower time bound — ISO 8601 (e.g. 2026-01-12T09:30:00Z) or Unix seconds. Defaults to start-of-trading-day.

  • endstring

    Upper time bound — ISO 8601 or Unix seconds. Defaults to now.

  • limitintegerdefault 50min 1 · max 500
  • only_sweepsbooleandefault false
  • only_multi_legbooleandefault false
  • exclude_multi_legbooleandefault false
  • moneynessstring
    ITMATMOTM
  • min_moneyness_pctnumberdouble
  • max_moneyness_pctnumberdouble
  • min_premiumnumberdoublemin 0
  • min_dteinteger
  • max_dteinteger
  • min_strikenumberdouble
  • max_strikenumberdouble
  • expirationstringdate

Responses

  • 200

    Filtered enriched trades.

  • 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

  • dataobject[]required
    • dateintegerrequired

      Days since 1970-01-01 (compact session date).

    • tsEventintegerint64required

      Trade event timestamp in milliseconds since epoch.

    • tsEventUsintegerint64

      Microsecond-precision timestamp (contract-trades endpoint only).

    • instrumentIdintegerint64required
    • rawSymbolstringrequired
    • tickerstringrequired
    • expirationintegerrequired

      Expiration as days since 1970-01-01.

    • strikenumberdoublerequired
    • rightstringrequired
      CP
    • dteintegerrequired
    • pricenumberdoublerequired
    • sizeintegerrequired
    • sidestringrequired

      Granular execution-side label — BB (below bid), B (bid), AB (above bid), M (mid), BA (below ask), A (ask), AA (above ask), or N (no BBO).

      BBBABMBAAAAN
    • publisherIdintegerrequired
    • bidPxnumber | nulldouble
    • askPxnumber | nulldouble
    • bidSzinteger | null
    • askSzinteger | null
    • neutralSzintegerrequired
    • totalPremiumnumberdoublerequired
    • spreadnumber | nulldouble
    • underlyingPricenumberdoublerequired
    • ivnumber | nulldouble
    • moneynessstringrequired
      ITMATMOTM
    • moneynessPercentnumberdoublerequired
    • openInterestintegerrequired
    • prevOiintegerrequired
    • prevClosenumber | nulldouble
    • prevCloseAgeinteger | null

      Trading days back the prevClose came from (0 = yesterday).

    • priceChangenumber | nulldouble
    • dailyVolumeintegerrequired
    • sweepTradebooleanrequired
    • blockTradebooleanrequired
    • multiLegbooleanrequired
    • crossTradebooleanrequired

      Pre-negotiated cross (OPRA condition 127): both sides were matched before the print, so side says nothing about who initiated it.

    • ivDirectionintegerrequired

      -1 = down, 0 = flat/unknown, 1 = up.

      -101
    • ingestionTimestampintegerint64required

      Server ingest time in milliseconds since epoch.

    • prevIvnumber | nulldouble
    • nextIvnumber | nulldouble
    • premiumPercentileinteger

      Bucketed premium percentile band (0 = below P50, 99 = P99+).

      05075909599
    • flowScoreinteger
    • chainBidPctnumberdouble
    • chainAskPctnumberdouble
    • contractBidPctnumberdouble
    • contractAskPctnumberdouble
    • aggCountinteger
    • aggTotalPremiumnumberdouble
    • aggTotalSizeinteger
    • mlSiblingboolean

      True when this leg was included via spread association rather than its own filter match.

    • strategyGroupIdstring
    • strategyTypestring
    • strategyLegCountinteger
    • earningsDteinteger
    • nextEarningsDateinteger | null
    • cacheMissboolean
    • sectorstring
    • industrystring
  • 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?