Unusual Activity

Unusual options activity scan

Contract-level unusual options activity across the covered universe. Defaults to the latest scan day. Filter by symbols, side and every numeric threshold.

Ordering and paging. Rows are ranked by score = volume_oi_ratio * ln(premium_estimate + 1) descending, then data_date, symbol, option_symbol ascending, so limit + offset paging is deterministic. The envelope reports filtered_total (rows matching the filters across all pages) and has_more. Row identity is (data_date, symbol, option_symbol).

Freshness. The current day is upserted every 5 minutes during the regular session (rows added or updated, never removed); past days are immutable. since selects contracts whose last_seen_at is at or after the timestamp - a polling window, not a monotonic cursor. On this endpoint since combines with the day scope (latest day unless date / date_from / date_to is set), so poll with a few minutes of overlap and de-duplicate on the row identity.

Base floor. Unless raw=1, rows must satisfy Vol/OI >= 1.5, open interest >= 100 and premium >= $25,000.

get/options-flow/unusual

Request

  • Base URL: https://optionsbell.com/api/v1
  • URL: https://optionsbell.com/api/v1/options-flow/unusual
  • Auth: API key in header X-API-Key

Query parameters

datestring date

A specific trading day, YYYY-MM-DD (must be a real calendar day). Default is the latest available day.

date_fromstring date

Inclusive lower bound, YYYY-MM-DD.

date_tostring date

Inclusive upper bound, YYYY-MM-DD. Must not be before date_from (400 INVALID_DATE_RANGE).

sincestring date-time

ISO-8601 timestamp. Only contracts whose last_seen_at is at or after this instant. A polling window, not a monotonic cursor.

symbolsstring

Comma-separated tickers, case-insensitive (e.g. AAPL,NVDA). Tokens must match ^[A-Z][A-Z0-9.\-]{0,9}$; invalid tokens next to valid ones are dropped, no valid token at all is 400 INVALID_SYMBOLS.

type'c' | 'p' | 'all' | 'call' | 'calls' | 'put' | 'puts'

Contract side, case-insensitive: c / call / calls, p / put / puts, or all.

min_voloinumber

Minimum volume / open-interest ratio. Negative values are clamped to 0.

min_premiumnumber

Minimum estimated premium in USD (last_price * volume * 100). Negative values are clamped to 0.

min_ivnumber

Minimum implied volatility in percent (60 = 60%).

max_dteinteger

Maximum days to expiration. Floats are floored.

min_volumenumber

Minimum contract volume.

min_oinumber

Minimum open interest.

rawboolean

1 or true: skip the always-on base floor (Vol/OI >= 1.5, OI >= 100, premium >= $25k).

limitinteger

Max rows per page. Floats are floored; out-of-range values are clamped.

offsetinteger

Rows to skip. Combine with limit to enumerate every matching row; the envelope reports filtered_total and has_more.

Response

Ranked unusual contracts

datestring date nullable required

Resolved scan day; null in range mode or when the dataset is empty.

date_fromstring date nullable required
date_tostring date nullable required
sincestring date-time nullable required

Echo of the since filter (ISO-8601, UTC).

countinteger required

Rows in this response

limitinteger required
offsetinteger required
filtered_totalinteger required

Rows matching the filters across all pages (0 when the page is past the end).

has_moreboolean required
sort'score_desc,symbol,option_symbol' required

Example response

{
  "data": [
    {
      "symbol": "TSLA",
      "option_symbol": "TSLA|20260605|460.00P"
    }
  ]
}

Changes

No recorded changes to this operation across all 1 revision of this API.