Alert filters
GET
https://api.unusualwhales.com/api/alerts/filters
Request
Security:
Bearer Auth
Authorization: Bearer <token>
Responses
200 422 500Response Body 200 OK
access
object
Per alert type whether your account can create alerts of that type.
data
object
Per alert type (`noti_type`) the list of filter fields that can be used in the `config` object, each with its accepted values. `accepted_values` is either an array of allowed literal values, an object describing a nested structure, or one of these type tokens: - `bool`: true or false - `integer`: a whole number - `decimal`: a decimal number - `decimal_abs`: a decimal number that can optionally be wrapped as `abs(x)` or `|x|` to match on absolute value, e.g. `"min_delta": "abs(0.3)"` matches both delta 0.4 and delta -0.4 - `string`: a string - `list`: an array of values such as symbols, option contracts or dates - `object`: a nested object, see the filter's description
filter_descriptions
object
Per alert type a description of each filter field.
noti_type_descriptions
object
A description of each alert type.
rate_limits
object
Per alert type the maximum amount of alerts that trigger per day.
Try It
GET
Request Sample
curl -X GET "https://api.unusualwhales.com/api/alerts/filters" \
-H "Authorization: Bearer YOUR_API_KEY" \
-H "Accept: application/json"
Response Example
200
{
"access": {
"flow_alerts": true,
"option_trade": true,
"politician_trades": false
},
"data": {
"option_trade": [
{
"accepted_values": [
"all",
"watchlist_only",
"list"
],
"filter": "symbols"
},
{
"accepted_values": "list",
"filter": "option_contracts"
},
{
"accepted_values": "bool",
"description": "Filter for options expiring on OpEx (monthly expiration) Friday",
"filter": "opex_only"
},
{
"accepted_values": "bool",
"description": "Filter for options expiring on a quarterly OpEx (3rd Friday of Mar/Jun/Sep/Dec)",
"filter": "is_quarterly"
},
{
"accepted_values": [
"jan",
"feb",
"mar",
"apr",
"may",
"jun",
"jul",
"aug",
"sep",
"oct",
"nov",
"dec"
],
"description": "Filter for monthly opex expiries in any of these months",
"filter": "expiry_months"
},
{
"accepted_values": "bool",
"filter": "is_multi_leg"
},
{
"accepted_values": "bool",
"filter": "is_otm"
},
{
"accepted_values": "bool",
"description": "Trade size exceeds total open interest",
"filter": "size_greater_oi"
},
{
"accepted_values": "bool",
"description": "Daily volume exceeds total open interest",
"filter": "volume_greater_oi"
},
{
"accepted_values": "bool",
"description": "Filter for opening transactions only (new positions)",
"filter": "opening"
},
{
"accepted_values": "bool",
"description": "Exclude deep in-the-money contracts",
"filter": "exclude_deep_itm"
},
{
"accepted_values": "bool",
"description": "Include aggregated/block trades",
"filter": "add_agg_trades"
},
{
"accepted_values": [
"ask_side",
"bid_side",
"mid_side",
"no_side",
"china",
"volatility",
"dividend",
"index",
"arbitrage"
],
"filter": "excluded_tags"
},
{
"accepted_values": [
"ask_side",
"bid_side",
"mid_side",
"no_side",
"china",
"volatility",
"dividend",
"index",
"arbitrage"
],
"filter": "tags"
},
{
"accepted_values": [
"Common Stock",
"ETF",
"ADR",
"Index"
],
"filter": "issue_types"
},
{
"accepted_values": "list",
"filter": "industries"
},
{
"accepted_values": [
"Basic Materials",
"Communication Services",
"Consumer Cyclical",
"Consumer Defensive",
"Energy",
"Financial Services",
"Healthcare",
"Industrials",
"Real Estate",
"Technology",
"Utilities"
],
"filter": "sectors"
},
{
"accepted_values": [
"GMNI",
"XCBO",
"BATO",
"XBXO",
"MPRL",
"C2OX",
"AMXO",
"MCRY",
"ARCO",
"EDGO",
"XISX",
"XNDQ",
"XMIO",
"XPHO",
"XBOX",
"EMLD",
"MXOP",
"SPHR",
"MXTO",
"IEXO"
],
"filter": "exchanges"
},
{
"accepted_values": [
"Canc",
"Oseq",
"Cncl",
"Late",
"Cnco",
"Open",
"Cnol",
"Opnl",
"Auto",
"Reop",
"Isoi",
"Slan",
"Slai",
"Slcn",
"Slci",
"Slft",
"Mlet",
"Mlat",
"Mlct",
"Mlft",
"Mesl",
"Tlat",
"Masl",
"Mfsl",
"Tlet",
"Tlct",
"Tlft",
"Tesl",
"Tasl",
"Tfsl",
"Cbmo",
"Mctp",
"Exht"
],
"filter": "trade_codes"
},
{
"accepted_values": "list",
"filter": "expiry_dates"
},
{
"accepted_values": [
"micro",
"small",
"mid",
"large",
"big"
],
"filter": "marketcap_size"
},
{
"accepted_values": [
"opening",
"closing",
"reopening",
"cross_trade",
"extended_hours",
"intermarket_sweep",
"trade_through_exempt",
"odd_lot",
"official_price_report",
"futures_floor",
"summary",
"printable",
"normal"
],
"filter": "report_flags"
},
{
"accepted_values": "decimal",
"description": "Volume to open interest ratio (>1.0 = volume exceeds OI)",
"filter": "min_volume_oi_ratio"
},
{
"accepted_values": "decimal",
"description": "Volume to open interest ratio (>1.0 = volume exceeds OI)",
"filter": "max_volume_oi_ratio"
},
{
"accepted_values": [
"call",
"put"
],
"filter": "type"
},
{
"accepted_values": [
"am",
"pm",
"asian",
"cliquet"
],
"filter": "settlement"
},
{
"accepted_values": {
"arith_ops": [
"add",
"sub",
"mul",
"div"
],
"cmp_ops": [
"gt",
"gte",
"lt",
"lte",
"eq",
"neq"
],
"fields": [
"spot",
"strike",
"bid",
"ask",
"ewma_bid",
"ewma_ask",
"premium",
"price",
"size",
"volume",
"open_int",
"dte",
"delta",
"gamma",
"vega",
"theta",
"rho",
"theo",
"iv",
"marketcap",
"diff",
"spread",
"bid_perc",
"ask_perc",
"bull_perc",
"bear_perc",
"earnings_dte",
"days_between_expiry_and_earnings",
"vol_oi_ratio"
]
},
"description": "Cross field comparison",
"filter": "compare"
},
{
"accepted_values": "decimal",
"filter": "min_underlying_price"
},
{
"accepted_values": "decimal",
"filter": "max_underlying_price"
},
{
"accepted_values": "decimal",
"filter": "min_strike"
},
{
"accepted_values": "decimal",
"filter": "max_strike"
},
{
"accepted_values": "decimal",
"filter": "min_premium"
},
{
"accepted_values": "decimal",
"filter": "max_premium"
},
{
"accepted_values": "decimal",
"filter": "min_price"
},
{
"accepted_values": "decimal",
"filter": "max_price"
},
{
"accepted_values": "integer",
"filter": "min_size"
},
{
"accepted_values": "integer",
"filter": "max_size"
},
{
"accepted_values": "integer",
"filter": "min_volume"
},
{
"accepted_values": "integer",
"filter": "max_volume"
},
{
"accepted_values": "integer",
"filter": "min_open_interest"
},
{
"accepted_values": "integer",
"filter": "max_open_interest"
},
{
"accepted_values": "integer",
"filter": "min_dte"
},
{
"accepted_values": "integer",
"filter": "max_dte"
},
{
"accepted_values": "decimal_abs",
"filter": "min_delta"
},
{
"accepted_values": "decimal_abs",
"filter": "max_delta"
},
{
"accepted_values": "decimal_abs",
"filter": "min_gamma"
},
{
"accepted_values": "decimal_abs",
"filter": "max_gamma"
},
{
"accepted_values": "decimal_abs",
"filter": "min_theta"
},
{
"accepted_values": "decimal_abs",
"filter": "max_theta"
},
{
"accepted_values": "decimal_abs",
"description": "Implied volatility of the contract (decimal: 0.5 = 50%)",
"filter": "min_iv"
},
{
"accepted_values": "decimal_abs",
"description": "Implied volatility of the contract (decimal: 0.5 = 50%)",
"filter": "max_iv"
},
{
"accepted_values": "decimal",
"filter": "min_marketcap"
},
{
"accepted_values": "decimal",
"filter": "max_marketcap"
},
{
"accepted_values": "decimal_abs",
"description": "Stock price percentage change (decimal: 0.1 = 10%)",
"filter": "min_diff"
},
{
"accepted_values": "decimal_abs",
"description": "Stock price percentage change (decimal: 0.1 = 10%)",
"filter": "max_diff"
},
{
"accepted_values": "decimal",
"description": "Bid-ask spread percentage",
"filter": "min_spread"
},
{
"accepted_values": "decimal",
"description": "Bid-ask spread percentage",
"filter": "max_spread"
},
{
"accepted_values": "decimal_abs",
"description": "Percentage of volume traded at the bid price",
"filter": "min_bid_perc"
},
{
"accepted_values": "decimal_abs",
"description": "Percentage of volume traded at the bid price",
"filter": "max_bid_perc"
},
{
"accepted_values": "decimal_abs",
"description": "Percentage of volume traded at the ask price",
"filter": "min_ask_perc"
},
{
"accepted_values": "decimal_abs",
"description": "Percentage of volume traded at the ask price",
"filter": "max_ask_perc"
},
{
"accepted_values": "decimal_abs",
"description": "Percentage of bullish flow (calls at ask + puts at bid)",
"filter": "min_bull_perc"
},
{
"accepted_values": "decimal_abs",
"description": "Percentage of bullish flow (calls at ask + puts at bid)",
"filter": "max_bull_perc"
},
{
"accepted_values": "decimal_abs",
"description": "Percentage of bearish flow (calls at bid + puts at ask)",
"filter": "min_bear_perc"
},
{
"accepted_values": "decimal_abs",
"description": "Percentage of bearish flow (calls at bid + puts at ask)",
"filter": "max_bear_perc"
},
{
"accepted_values": "integer",
"description": "Days until next earnings report",
"filter": "min_earnings_dte"
},
{
"accepted_values": "integer",
"description": "Days until next earnings report",
"filter": "max_earnings_dte"
},
{
"accepted_values": "integer",
"description": "Minimum (contract_expiry - next_earnings_date) in calendar days — signed",
"filter": "min_days_between_expiry_and_earnings"
},
{
"accepted_values": "integer",
"description": "Maximum (contract_expiry - next_earnings_date) in calendar days — signed",
"filter": "max_days_between_expiry_and_earnings"
},
{
"accepted_values": "decimal_abs",
"description": "Bull/bear skew ratio",
"filter": "min_skew"
},
{
"accepted_values": "decimal_abs",
"description": "Bull/bear skew ratio",
"filter": "max_skew"
}
]
},
"filter_descriptions": {
"option_trade": [
{
"opening": "Filter for opening transactions only (new positions)"
},
{
"min_iv": "Implied volatility of the contract (decimal: 0.5 = 50%)"
}
]
},
"noti_type_descriptions": {
"option_trade": "Get notified about any new option trades that hit the flow"
},
"rate_limits": {
"flow_alerts": "500",
"option_trade": "5000"
}
}