Flow Alerts

curl --request GET \
  --url https://api.unusualwhales.com/api/option-trades/flow-alerts \
  --header 'Authorization: Bearer <token>'

import requests

url = "https://api.unusualwhales.com/api/option-trades/flow-alerts"

headers = {"Authorization": "Bearer <token>"}

response = requests.get(url, headers=headers)

print(response.text)

const options = {method: 'GET', headers: {Authorization: 'Bearer <token>'}};

fetch('https://api.unusualwhales.com/api/option-trades/flow-alerts', options)
  .then(res => res.json())
  .then(res => console.log(res))
  .catch(err => console.error(err));

<?php

$curl = curl_init();

curl_setopt_array($curl, [
  CURLOPT_URL => "https://api.unusualwhales.com/api/option-trades/flow-alerts",
  CURLOPT_RETURNTRANSFER => true,
  CURLOPT_ENCODING => "",
  CURLOPT_MAXREDIRS => 10,
  CURLOPT_TIMEOUT => 30,
  CURLOPT_HTTP_VERSION => CURL_HTTP_VERSION_1_1,
  CURLOPT_CUSTOMREQUEST => "GET",
  CURLOPT_HTTPHEADER => [
    "Authorization: Bearer <token>"
  ],
]);

$response = curl_exec($curl);
$err = curl_error($curl);

curl_close($curl);

if ($err) {
  echo "cURL Error #:" . $err;
} else {
  echo $response;
}

package main

import (
	"fmt"
	"net/http"
	"io"
)

func main() {

	url := "https://api.unusualwhales.com/api/option-trades/flow-alerts"

	req, _ := http.NewRequest("GET", url, nil)

	req.Header.Add("Authorization", "Bearer <token>")

	res, _ := http.DefaultClient.Do(req)

	defer res.Body.Close()
	body, _ := io.ReadAll(res.Body)

	fmt.Println(string(body))

}

require 'uri'
require 'net/http'

url = URI("https://api.unusualwhales.com/api/option-trades/flow-alerts")

http = Net::HTTP.new(url.host, url.port)
http.use_ssl = true

request = Net::HTTP::Get.new(url)
request["Authorization"] = 'Bearer <token>'

response = http.request(request)
puts response.read_body

{
  "data": [
    {
      "alert_rule": "RepeatedHits",
      "all_opening_trades": false,
      "created_at": "2023-12-12T16:35:52.168Z",
      "expiry": "2023-12-22T00:00:00.000Z",
      "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"
    }
  ]
}

{
  "code": "authentication_required",
  "documentation_url": "https://api.unusualwhales.com/docs",
  "expected_format": "uuid",
  "message": "The API token provided is not in the expected format. Unusual Whales API tokens are UUIDs, such as 123e4567-e89b-12d3-a456-426614174000.",
  "reason": "malformed_token",
  "request_id": "GNI_YTC1CRnw2LACGBvE",
  "retryable": false,
  "support_email": "[email protected]",
  "token_url": "https://unusualwhales.com/dashboard/api"
}

{
  "code": "missing_access",
  "documentation_url": "https://api.unusualwhales.com/docs",
  "message": "The API token provided is valid but is not permitted to access this route.",
  "reason": "route_not_permitted",
  "request_id": "GNI_YTC1CRnw2LACGBvE",
  "retryable": false,
  "support_email": "[email protected]",
  "token_url": "https://unusualwhales.com/dashboard/api"
}

{
  "msg": "Invalid path input: MSFT12 (valid example: AAPL) - Invalid query input(s): date=2023-02-140 (valid example: date=2024-01-18)",
  "path": "/api/darkpool/MSFT12",
  "query": "date=2023-02-140",
  "url": "localhost:4000/api/darkpool/MSFT12?date=2023-02-140"
}

"Something went wrong"

option-trade

Flow Alerts

Flow alerts are rule based aggregations on the full tape of option trades.

While there are quite a few different rules and alerts the most used one is the repeated hit family: RepeatedHits, RepeatedHitsAscendingFill, RepeatedHitsDescendingFill

Each of those represent an alert when there have been multiple transactions on the same option contract within a few milliseconds. This can be mean that a single order is being matched across multiple other orders and creating multiple transactions. It can also just mean that there are multiple buyers/sellers at the same time.

Trades usually use the repeated hits with other data points to form a picture on whether there is some urgency in entering/exiting a position in a contract/ticker.

The full current options tape including trades that do not form a RepeatedHits alert can be accessed through the Option Trades endpoint. The difference between the 3 repeated hits alerts are:

DescendingFill: Each transaction that comes after another in chronological order has either the same fill price as or a lower fill price than the previous transaction. The last transaction must be lower than the first transaction.
AscendingFill: The opposite of DescendingFill. The fill prices increase instead of decreasing.
RepeatedHits (neither ascending nor descending): When it does not fit into one of the first two categories.

To express ascending and descending in a mathmatical notion. Let p₁, p₂, …, pₙ be the fill prices of n transactions ordered chronologically:

DescendingFill: pᵢ ≥ pᵢ₊₁ for all i ∈ [1, n−1], and pₙ < p₁.
AscendingFill: pᵢ ≤ pᵢ₊₁ for all i ∈ [1, n−1], and pₙ > p₁.

For the individual flow alert rules and how the aggregation is based on you can checkout out https://unusualwhales.com/option-flow-alerts/rules.

For any given flow alert you can take a look at the individual trades that are making up the alert by taking the alert’s id and use https://api.unusualwhales.com/docs/operations/PublicApi.OptionTradeController.flow_alert to retrieve the individual transactions.

For real time streaming of flow alerts, subscribe to the flow-alerts websocket channel, see https://api.unusualwhales.com/docs/websocket/flow-alerts.

The 14-day lookback limit on the custom alerts endpoint (/api/alerts) does not apply to this endpoint.

GET

api

option-trades

flow-alerts

Flow Alerts

curl --request GET \
  --url https://api.unusualwhales.com/api/option-trades/flow-alerts \
  --header 'Authorization: Bearer <token>'

import requests

url = "https://api.unusualwhales.com/api/option-trades/flow-alerts"

headers = {"Authorization": "Bearer <token>"}

response = requests.get(url, headers=headers)

print(response.text)

const options = {method: 'GET', headers: {Authorization: 'Bearer <token>'}};

fetch('https://api.unusualwhales.com/api/option-trades/flow-alerts', options)
  .then(res => res.json())
  .then(res => console.log(res))
  .catch(err => console.error(err));

<?php

$curl = curl_init();

curl_setopt_array($curl, [
  CURLOPT_URL => "https://api.unusualwhales.com/api/option-trades/flow-alerts",
  CURLOPT_RETURNTRANSFER => true,
  CURLOPT_ENCODING => "",
  CURLOPT_MAXREDIRS => 10,
  CURLOPT_TIMEOUT => 30,
  CURLOPT_HTTP_VERSION => CURL_HTTP_VERSION_1_1,
  CURLOPT_CUSTOMREQUEST => "GET",
  CURLOPT_HTTPHEADER => [
    "Authorization: Bearer <token>"
  ],
]);

$response = curl_exec($curl);
$err = curl_error($curl);

curl_close($curl);

if ($err) {
  echo "cURL Error #:" . $err;
} else {
  echo $response;
}

package main

import (
	"fmt"
	"net/http"
	"io"
)

func main() {

	url := "https://api.unusualwhales.com/api/option-trades/flow-alerts"

	req, _ := http.NewRequest("GET", url, nil)

	req.Header.Add("Authorization", "Bearer <token>")

	res, _ := http.DefaultClient.Do(req)

	defer res.Body.Close()
	body, _ := io.ReadAll(res.Body)

	fmt.Println(string(body))

}

require 'uri'
require 'net/http'

url = URI("https://api.unusualwhales.com/api/option-trades/flow-alerts")

http = Net::HTTP.new(url.host, url.port)
http.use_ssl = true

request = Net::HTTP::Get.new(url)
request["Authorization"] = 'Bearer <token>'

response = http.request(request)
puts response.read_body

{
  "data": [
    {
      "alert_rule": "RepeatedHits",
      "all_opening_trades": false,
      "created_at": "2023-12-12T16:35:52.168Z",
      "expiry": "2023-12-22T00:00:00.000Z",
      "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"
    }
  ]
}

{
  "code": "authentication_required",
  "documentation_url": "https://api.unusualwhales.com/docs",
  "expected_format": "uuid",
  "message": "The API token provided is not in the expected format. Unusual Whales API tokens are UUIDs, such as 123e4567-e89b-12d3-a456-426614174000.",
  "reason": "malformed_token",
  "request_id": "GNI_YTC1CRnw2LACGBvE",
  "retryable": false,
  "support_email": "[email protected]",
  "token_url": "https://unusualwhales.com/dashboard/api"
}

{
  "code": "missing_access",
  "documentation_url": "https://api.unusualwhales.com/docs",
  "message": "The API token provided is valid but is not permitted to access this route.",
  "reason": "route_not_permitted",
  "request_id": "GNI_YTC1CRnw2LACGBvE",
  "retryable": false,
  "support_email": "[email protected]",
  "token_url": "https://unusualwhales.com/dashboard/api"
}

{
  "msg": "Invalid path input: MSFT12 (valid example: AAPL) - Invalid query input(s): date=2023-02-140 (valid example: date=2024-01-18)",
  "path": "/api/darkpool/MSFT12",
  "query": "date=2023-02-140",
  "url": "localhost:4000/api/darkpool/MSFT12?date=2023-02-140"
}

"Something went wrong"

Authorizations

Authorization

string

header

required

Bearer authentication header of the form Bearer <token>, where <token> is your auth token.

Query Parameters

ticker_symbol

string

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

Example:

"AAPL,INTC"

unusual

boolean

Convenience preset for "unusual" flow, matching the 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

integer

The minimum premium on that alert. Min: 0.

Required range: x >= 0

Example:

12500.5

max_premium

integer

The maximum premium on that alert. Min: 0.

Required range: x >= 0

Example:

12500.5

min_size

integer

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.

Required range: x >= 0

Example:

125

max_size

integer

The maximum size on that alert. Min: 0.

Required range: x >= 0

Example:

125

min_volume

integer

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

Required range: x >= 0

Example:

125

max_volume

integer

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

Required range: x >= 0

Example:

125

min_open_interest

integer

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

Required range: x >= 0

Example:

125

max_open_interest

integer

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

Required range: x >= 0

Example:

125

all_opening

boolean

default:true

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

is_floor

boolean

default:true

Boolean flag whether a transaction is from the floor.

Example:

true

is_sweep

boolean

default:true

Boolean flag whether a transaction is a intermarket sweep.

Example:

true

is_call

boolean

default:true

Boolean flag whether a transaction is a call.

Example:

true

is_put

boolean

default:true

Boolean flag whether a transaction is a put.

Example:

true

is_ask_side

boolean

default:true

Boolean flag whether a transaction is ask side.

Example:

true

is_bid_side

boolean

default:true

Boolean flag whether a transaction is bid side.

Example:

true

rule_name[]

enum<string>[]

An array of 1 or more rule name.

Available options:

FloorTradeSmallCap,

FloorTradeMidCap,

RepeatedHits,

RepeatedHitsAscendingFill,

RepeatedHitsDescendingFill,

FloorTradeLargeCap,

OtmEarningsFloor,

LowHistoricVolumeFloor,

SweepsFollowedByFloor

Example:

["RepeatedHits", "RepeatedHitsAscendingFill"]

min_diff

string

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

string

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

number

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.

Required range: x >= 0

Example:

0.32

max_volume_oi_ratio

number

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.

Required range: x >= 0

Example:

1.58

is_otm

boolean

Only include contracts which are currently out of the money.

Example:

true

issue_types[]

enum<string>[]

An array of 1 or more issue types.

A singular issue type.

Available options:

Common Stock,

ETF,

Index,

ADR

Example:

["Common Stock", "Index"]

min_dte

integer

The minimum days to expiry. Min: 0.

Required range: x >= 0

Example:

1

max_dte

integer

The maximum days to expiry. Min: 0.

Required range: x >= 0

Example:

3

min_ask_perc

number

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

Required range: 0 <= x <= 1

Example:

0.25

max_ask_perc

number

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

Required range: 0 <= x <= 1

Example:

0.75

min_bid_perc

number

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

Required range: 0 <= x <= 1

Example:

0.25

max_bid_perc

number

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

Required range: 0 <= x <= 1

Example:

0.75

min_bull_perc

number

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

Required range: 0 <= x <= 1

Example:

0.5

max_bull_perc

number

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

Required range: 0 <= x <= 1

Example:

0.9

min_bear_perc

number

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

Required range: 0 <= x <= 1

Example:

0.5

max_bear_perc

number

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

Required range: 0 <= x <= 1

Example:

0.9

min_skew

number

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

Required range: 0 <= x <= 1

Example:

0.3

max_skew

number

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

Required range: 0 <= x <= 1

Example:

0.7

min_price

number

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

Required range: x >= 0

Example:

10.5

max_price

number

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

Required range: x >= 0

Example:

500.75

min_iv_change

number

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

Example:

0.01

max_iv_change

number

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

Example:

0.05

min_size_vol_ratio

number

The minimum size to volume ratio. Min: 0.

Required range: x >= 0

Example:

1.5

max_size_vol_ratio

number

The maximum size to volume ratio. Min: 0.

Required range: x >= 0

Example:

10

min_spread

number

The minimum spread. Min: 0.

Required range: x >= 0

Example:

0.05

max_spread

number

The maximum spread. Min: 0.

Required range: x >= 0

Example:

5

min_marketcap

number

The minimum marketcap. Min: 0.

Required range: x >= 0

Example:

1000000

max_marketcap

number

The maximum marketcap. Min: 0.

Required range: x >= 0

Example:

250000000

is_multi_leg

boolean

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

Example:

true

size_greater_oi

boolean

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

Example:

true

vol_greater_oi

boolean

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

Example:

true

min_days_between_expiry_and_earnings

integer

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

integer

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

string

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

string

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

integer

default:100

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

Required range: 1 <= x <= 200

Example:

10

Response

Representation of a flow alert.

alert_rule

string

The name of the alert rule.

Example:

"RepeatedHits"

all_opening_trades

boolean

Example:

false

created_at

string

A UTC timestamp.

Example:

"2023-12-12T16:35:52.168Z"

delta

number<double> | null

Size weighted delta of all transactions that make up the flow alert. Null when unavailable.

expiry

string

The contract expiry date in ISO format.

Example:

"2023-12-22T00:00:00.000Z"

expiry_count

integer

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

Example:

2

gamma

number<double> | null

Size weighted gamma of all transactions that make up the flow alert. Null when unavailable.

has_floor

boolean

Example:

false

has_multileg

boolean

Whether the trade is a multileg trade.

Example:

false

has_singleleg

boolean

Whether the trade is a singleleg trade.

Example:

true

has_sweep

boolean

Whether the trade is a sweep.

Example:

true

issue_type

enum<string>

The issue type of the ticker.

Available options:

Common Stock,

ETF,

Index,

ADR

Example:

"Common Stock"

number<double> | null

Size weighted implied volatility of all transactions that make up the flow alert. Null when unavailable.

open_interest

any

option_chain

string

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

any

rho

number<double> | null

Size weighted rho of all transactions that make up the flow alert. Null when unavailable.

strike

string

The contract strike.

Example:

"375"

theo

number<double> | null

Size weighted theoretical option price of all transactions that make up the flow alert. Null when unavailable.

theta

number<double> | null

Size weighted theta of all transactions that make up the flow alert. Null when unavailable.

ticker

any

total_ask_side_prem

any

total_bid_side_prem

any

total_premium

any

total_size

any

trade_count

any

type

enum<string>

The contract type.

Available options:

call,

put

Example:

"call"

underlying_price

any

vega

number<double> | null

Size weighted vega of all transactions that make up the flow alert. Null when unavailable.

volume

any

volume_oi_ratio

any

Last modified on September 29, 2026

Docs

Endpoints

Flow Alerts

Authorizations

Query Parameters

Response