API / Documentation

Public API Pricing Enterprise MCP API Docs Kafka Streaming OpenAPI YAML

UnusualWhales API

Flow Alerts

GET https://api.unusualwhales.com/api/option-trades/flow-alerts

Request

Security: Bearer Auth Authorization: Bearer <token>

Query Parameters

ticker_symbol Ticker optional

A comma separated list of tickers. To exclude certain tickers prefix the first ticker with a `-`.

Example: AAPL,INTC

unusual boolean optional

Convenience preset for "unusual" flow, matching the [live options flow](https://unusualwhales.com/live-options-flow) default criteria: volume>OI, size>OI, all-opening, OTM, single-leg, DTE≤60, ask-side≥50%, premium≥$10k, size≥5, issue types ADR/Common Stock/ETF. Applied as defaults, so any of those filters you pass explicitly (e.g. `min_ask_perc=0.9`, `max_dte=40`) overrides the preset.

min_premium optional

The minimum premium on that alert. Min: 0.

Example: 12500.5

>= 0

max_premium optional

The maximum premium on that alert. Min: 0.

Example: 12500.5

>= 0

min_size optional

The minimum size on that alert. Size is defined as the sum of the sizes of all transactions that make up the alert. Min: 0.

Example: 125

>= 0

max_size optional

The maximum size on that alert. Min: 0.

Example: 125

>= 0

min_volume optional

The minimum volume on that alert's contract at the time of the alert. Min: 0.

Example: 125

>= 0

max_volume optional

The maximum volume on that alert's contract at the time of the alert. Min: 0.

Example: 125

>= 0

min_open_interest optional

The minimum open interest on that alert's contract at the time of the alert. Min: 0.

Example: 125

>= 0

max_open_interest optional

The maximum open interest on that alert's contract at the time of the alert. Min: 0.

Example: 125

>= 0

all_opening optional

Boolean flag whether all transactions are opening transactions based on OI, Size & Volume. Since Flow Alerts with rule_name values of RepeatedHits, RepeatedHitsAscendingFill, and RepeatedHitsDescendingFill are composed of many individual transactions, it is extremely unlikely that the all_opening value will be true, so if you are interested in these Flow Alerts you should not set this query param to true.

Example: true Default: true

is_floor optional

Boolean flag whether a transaction is from the floor.

Example: true Default: true

is_sweep optional

Boolean flag whether a transaction is a intermarket sweep.

Example: true Default: true

is_call optional

Boolean flag whether a transaction is a call.

Example: true Default: true

is_put optional

Boolean flag whether a transaction is a put.

Example: true Default: true

is_ask_side optional

Boolean flag whether a transaction is ask side.

Example: true Default: true

is_bid_side optional

Boolean flag whether a transaction is bid side.

Example: true Default: true

rule_name[] Rule Name optional

An array of 1 or more rule name.

Example: RepeatedHitsRepeatedHitsAscendingFill

enum: FloorTradeSmallCap, FloorTradeMidCap, RepeatedHits, RepeatedHitsAscendingFill, RepeatedHitsDescendingFill, FloorTradeLargeCap, OtmEarningsFloor, LowHistoricVolumeFloor, SweepsFollowedByFloor

min_diff Min Contract Diff optional

The minimum OTM diff of a contract. Given a strike price of 120 and an underlying price of 98 the diff for a call option would equal to: (120 - 98) / 98 = 0.2245 The diff for a put option would equal to: -1 * (120 - 98) / 98 = -0.2245.

Example: 0.53

max_diff Min Contract Diff optional

The minimum OTM diff of a contract. Given a strike price of 120 and an underlying price of 98 the diff for a call option would equal to: (120 - 98) / 98 = 0.2245 The diff for a put option would equal to: -1 * (120 - 98) / 98 = -0.2245.

Example: 0.53

min_volume_oi_ratio Min Volume OI Ratio optional

The minimum ratio of contract volume to contract open interest. If the open interest of a contract is zero, then this ratio is evaluated as if the open interest of the contract was one (to avoid divide by zero errors). For example, if you set this ratio to 10, then a contract with zero open interest and 7 volume will NOT be included in your results.

Example: 0.32

>= 0

max_volume_oi_ratio Max Volume OI Ratio optional

The maximum ratio of contract volume to contract open interest. If the open interest of a contract is zero, then this ratio is evaluated as if the open interest of the contract was one (to avoid divide by zero errors). For example, if you set this ratio to 50, then a contract with zero open interest and 75 volume will NOT be included in your results.

Example: 1.58

>= 0

is_otm Is OTM Contract optional

Only include contracts which are currently out of the money.

Example: true

issue_types[] Issue types optional

An array of 1 or more issue types.

Example: Common StockIndex

enum: Common Stock, ETF, Index, ADR

min_dte Min DTE optional

The minimum days to expiry. Min: 0.

Example: 1

>= 0

max_dte Max DTE optional

The maximum days to expiry. Min: 0.

Example: 3

>= 0

min_ask_perc Flow Alerts Min Ask Percentage optional

The minimum ask percentage. Decimal proxy for percentage (0 to 1). Min: 0. Max: 1.

Example: 0.25

>= 0 <= 1

max_ask_perc Flow Alerts Max Ask Percentage optional

The maximum ask percentage. Decimal proxy for percentage (0 to 1). Min: 0. Max: 1.

Example: 0.75

>= 0 <= 1

min_bid_perc Flow Alerts Min Bid Percentage optional

The minimum bid percentage. Decimal proxy for percentage (0 to 1). Min: 0. Max: 1.

Example: 0.25

>= 0 <= 1

max_bid_perc Flow Alerts Max Bid Percentage optional

The maximum bid percentage. Decimal proxy for percentage (0 to 1). Min: 0. Max: 1.

Example: 0.75

>= 0 <= 1

min_bull_perc Flow Alerts Min Bull Percentage optional

The minimum bull percentage. Decimal proxy for percentage (0 to 1). Min: 0. Max: 1.

Example: 0.5

>= 0 <= 1

max_bull_perc Flow Alerts Max Bull Percentage optional

The maximum bull percentage. Decimal proxy for percentage (0 to 1). Min: 0. Max: 1.

Example: 0.9

>= 0 <= 1

min_bear_perc Flow Alerts Min Bear Percentage optional

The minimum bear percentage. Decimal proxy for percentage (0 to 1). Min: 0. Max: 1.

Example: 0.5

>= 0 <= 1

max_bear_perc Flow Alerts Max Bear Percentage optional

The maximum bear percentage. Decimal proxy for percentage (0 to 1). Min: 0. Max: 1.

Example: 0.9

>= 0 <= 1

min_skew Flow Alerts Min Skew optional

The minimum skew. Decimal proxy for percentage (0 to 1). Min: 0. Max: 1.

Example: 0.3

>= 0 <= 1

max_skew Flow Alerts Max Skew optional

The maximum skew. Decimal proxy for percentage (0 to 1). Min: 0. Max: 1.

Example: 0.7

>= 0 <= 1

min_price Flow Alerts Min Price optional

The minimum price of the underlying asset. Min: 0.

Example: 10.5

>= 0

max_price Flow Alerts Max Price optional

The maximum price of the underlying asset. Min: 0.

Example: 500.75

>= 0

min_iv_change Flow Alerts Min IV Change optional

The minimum IV change. Unbounded decimal proxy for percentage (e.g., 0.01 for minimum +1% change).

Example: 0.01

max_iv_change Flow Alerts Max IV Change optional

The maximum IV change. Unbounded decimal proxy for percentage (e.g., 0.05 for maximum +5% change).

Example: 0.05

min_size_vol_ratio Flow Alerts Min Size Volume Ratio optional

The minimum size to volume ratio. Min: 0.

Example: 1.5

>= 0

max_size_vol_ratio Flow Alerts Max Size Volume Ratio optional

The maximum size to volume ratio. Min: 0.

Example: 10.0

>= 0

min_spread Flow Alerts Min Spread optional

The minimum spread. Min: 0.

Example: 0.05

>= 0

max_spread Flow Alerts Max Spread optional

The maximum spread. Min: 0.

Example: 5.0

>= 0

min_marketcap Min Marketcap optional

The minimum marketcap. Min: 0.

Example: 1000000

>= 0

max_marketcap Max Marketcap optional

The maximum marketcap. Min: 0.

Example: 250000000

>= 0

is_multi_leg Flow Alerts Is Multi Leg optional

Boolean flag whether the transaction is a multi-leg transaction.

Example: true

size_greater_oi Flow Alerts Size Greater Than Open Interest optional

Only include alerts where the size is greater than the open interest.

Example: true

vol_greater_oi Flow Alerts Volume Greater Than Open Interest optional

Only include alerts where the volume is greater than the open interest.

Example: true

min_days_between_expiry_and_earnings MinDaysBetweenExpiryAndEarnings optional

Minimum value of (contract_expiry_date - underlying_next_earnings_date) in days. Negative = contract expires BEFORE earnings; zero = same day; positive = AFTER earnings. Use together with `max_days_between_expiry_and_earnings` to target a window around the next earnings announcement. Examples: to exclude contracts that expire after the next earnings, set `max_days_between_expiry_and_earnings=-1`. To target contracts that expire the same week as (and after) earnings, set `min_days_between_expiry_and_earnings=1&max_days_between_expiry_and_earnings=6`. Contracts whose underlying has no known next earnings date are excluded whenever this filter is used.

Example: 1

max_days_between_expiry_and_earnings MaxDaysBetweenExpiryAndEarnings optional

Maximum value of (contract_expiry_date - underlying_next_earnings_date) in days. Negative = contract expires BEFORE earnings; zero = same day; positive = AFTER earnings. Use together with `min_days_between_expiry_and_earnings` to target a window around the next earnings announcement. Examples: to exclude contracts that expire after the next earnings, set `max_days_between_expiry_and_earnings=-1`. To target contracts that expire the same week as (and after) earnings, set `min_days_between_expiry_and_earnings=1&max_days_between_expiry_and_earnings=6`. Contracts whose underlying has no known next earnings date are excluded whenever this filter is used.

Example: 6

newer_than NewerThan optional

The unix time in milliseconds or seconds at which no older results will be returned. Can be used with `older_than` to paginate by time. Also accepts an ISO date or RFC 3339 datetime (example: 2024-01-25).

Example: 1_715_083_417

older_than OlderThan optional

The unix time in milliseconds or seconds at which no newer results will be returned. Can be used with `newer_than` to paginate by time. Also accepts an ISO date or RFC 3339 datetime (example: 2024-01-25).

Example: 1_715_083_417

limit Default 100 Max 200 Min 1 optional

How many items to return. Default: 100. Max: 200. Min: 1.

Example: 10 Default: 100

>= 1 <= 200

Responses

200 422 500

Response Body 200 OK

alert_rule Alert Rule Name

The name of the alert rule.

Example: RepeatedHits

all_opening_trades Option Contract All Opening Trades

created_at General UTC Timestamp

A UTC timestamp.

Example: 2023-12-12T16:35:52.168490Z

expiry Option Contract Expiry

The contract expiry date in ISO format.

Example: 2023-12-22

expiry_count Option Contract Expiry Count

The amount of expiries belonging to the trade. This is only greater than 1 if it is a multileg trade.

Example: 2

has_floor Option Contract Has Floor

has_multileg Single Trade Has Multileg

Whether the trade is a multileg trade.

has_singleleg Single Trade Is Single Leg

Whether the trade is a singleleg trade.

Example: true

has_sweep Single Trade Is Sweep

Whether the trade is a sweep.

Example: true

issue_type Stock Issue Type

The issue type of the ticker.

Example: Common Stock

open_interest ToBeDone

option_chain Option Contract Symbol

The option symbol of the contract. You can use the following regex to extract underlying ticker, option type, expiry & strike: `^(?<symbol>[\w]*)(?<expiry>(\d{2})(\d{2})(\d{2}))(?<type>[PC])(?<strike>\d{8})$` Keep in mind that the strike needs to be multiplied by 1,000.

price ToBeDone

strike Option Contract Strike

The contract strike.

Example: 375

ticker ToBeDone

total_ask_side_prem ToBeDone

total_bid_side_prem ToBeDone

total_premium ToBeDone

total_size ToBeDone

trade_count ToBeDone

type Option Contract Type

The contract type.

Example: call

underlying_price ToBeDone

volume ToBeDone

volume_oi_ratio ToBeDone

Try It GET

API Token

Query Parameters

ticker_symbol Ticker

unusual boolean

min_premium

max_premium

min_size

max_size

min_volume

max_volume

min_open_interest

max_open_interest

all_opening

is_floor

is_sweep

is_call

is_put

is_ask_side

is_bid_side

rule_name[] Rule Name

min_diff Min Contract Diff

max_diff Min Contract Diff

min_volume_oi_ratio Min Volume OI Ratio

max_volume_oi_ratio Max Volume OI Ratio

is_otm Is OTM Contract

issue_types[] Issue types

min_dte Min DTE

max_dte Max DTE

min_ask_perc Flow Alerts Min Ask Percentage

max_ask_perc Flow Alerts Max Ask Percentage

min_bid_perc Flow Alerts Min Bid Percentage

max_bid_perc Flow Alerts Max Bid Percentage

min_bull_perc Flow Alerts Min Bull Percentage

max_bull_perc Flow Alerts Max Bull Percentage

min_bear_perc Flow Alerts Min Bear Percentage

max_bear_perc Flow Alerts Max Bear Percentage

min_skew Flow Alerts Min Skew

max_skew Flow Alerts Max Skew

min_price Flow Alerts Min Price

max_price Flow Alerts Max Price

min_iv_change Flow Alerts Min IV Change

max_iv_change Flow Alerts Max IV Change

min_size_vol_ratio Flow Alerts Min Size Volume Ratio

max_size_vol_ratio Flow Alerts Max Size Volume Ratio

min_spread Flow Alerts Min Spread

max_spread Flow Alerts Max Spread

min_marketcap Min Marketcap

max_marketcap Max Marketcap

is_multi_leg Flow Alerts Is Multi Leg

size_greater_oi Flow Alerts Size Greater Than Open Interest

vol_greater_oi Flow Alerts Volume Greater Than Open Interest

min_days_between_expiry_and_earnings MinDaysBetweenExpiryAndEarnings

max_days_between_expiry_and_earnings MaxDaysBetweenExpiryAndEarnings

newer_than NewerThan

older_than OlderThan

limit Default 100 Max 200 Min 1

Request Sample

curl -X GET "https://api.unusualwhales.com/api/option-trades/flow-alerts" \
  -H "Authorization: Bearer YOUR_API_KEY" \
  -H "Accept: application/json"

import http.client

conn = http.client.HTTPSConnection("api.unusualwhales.com")
headers = {"Authorization": "Bearer YOUR_API_KEY", "Accept": "application/json"}
conn.request("GET", "/api/option-trades/flow-alerts", headers=headers)
response = conn.getresponse()
print(response.read().decode("utf-8"))

Response Example 200

{
  "data": [
    {
      "alert_rule": "RepeatedHits",
      "all_opening_trades": false,
      "created_at": "2023-12-12T16:35:52.168490Z",
      "expiry": "2023-12-22",
      "expiry_count": 1,
      "has_floor": false,
      "has_multileg": false,
      "has_singleleg": true,
      "has_sweep": true,
      "issue_type": "Common Stock",
      "open_interest": 7913,
      "option_chain": "MSFT231222C00375000",
      "price": "4.05",
      "strike": "375",
      "ticker": "MSFT",
      "total_ask_side_prem": "151875",
      "total_bid_side_prem": "405",
      "total_premium": "186705",
      "total_size": 461,
      "trade_count": 32,
      "type": "call",
      "underlying_price": "372.99",
      "volume": 2442,
      "volume_oi_ratio": "0.30860609124226"
    }
  ]
}