# Alert filters

`GET` `https://api.unusualwhales.com/api/alerts/filters`

Returns the available filters for creating alert configurations:
- `data`: per alert type (`noti_type`) the filter fields that can be used in the `config` object, each with its accepted values
- `access`: per alert type whether your account can create alerts of that type
- `noti_type_descriptions`: a description of each alert type
- `filter_descriptions`: per alert type a description of each filter field
- `rate_limits`: per alert type the maximum amount of alerts that trigger per day

Use this endpoint to determine which alert types the account can access and to build a structured `config` object.
Submit the resulting `noti_type` and `config` to `POST /api/alerts/configuration` to create an alert.

For more complex filters, fetch the Query language syntax and fields from `GET /api/alerts/query/grammar`,
then submit the Query expression to `POST /api/alerts/configuration` using `input` instead of `config`.
The `config` and `input` fields are mutually exclusive.


## Authentication

```
Authorization: Bearer YOUR_API_KEY
```


## Response (200)

| Field | Type | Description |
|-------|------|-------------|
| `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. |


## Example

### curl

```bash
curl -X GET "https://api.unusualwhales.com/api/alerts/filters" \
  -H "Authorization: Bearer YOUR_API_KEY" \
  -H "Accept: application/json"
```

### Python

```python
import http.client

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

## Response Example

```json
{
  "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"
  }
}
```