Unusual Whales API - Alerts endpoints (AlertsController)

Unusual Whales API - Alerts endpoints

Reference for the UW AlertsController surface. Two endpoints: read alerts that have fired against your account, and read the config behind those alerts. This is account-scoped (your saved alert configs + their firings), not market-wide.

1. Base contract

Property	Value
Base URL	https://api.unusualwhales.com
Auth	Authorization: Bearer <token> header
Response envelope	{ "data": [ ... ] }
Status codes	200, 422, 500
Rate limits	Not specified in per-endpoint docs

2. Endpoint matrix

#	Path	Purpose
1	GET /api/alerts	List alerts that have fired (your account’s alert feed)
2	GET /api/alerts/configuration	List the alert configs (the rules behind the firings)

3. GET /api/alerts - Fired alerts

Returns alerts that triggered against your saved configurations. Time-windowed, paginated, filterable by alert type and ticker.

3.1 Query parameters

Param	Type	Required	Default	Notes
limit	int	no	50	Min 1, max 500
intraday_only	bool	no	true	If false, includes overnight/multi-day alerts
config_ids[]	array of UUIDs	no	-	Filter to specific saved configs
ticker_symbols	string	no	-	Comma-separated tickers (SPY,QQQ,AAPL)
noti_types[]	array of strings	no	-	See full list below
newer_than	string (ISO 8601 or unix)	no	-	Max 14 days forward
older_than	string (ISO 8601 or unix)	no	-	Max 14 days backward

Important window constraint. Both newer_than and older_than are capped at ~14 days from now. The API will not serve alerts older than two weeks via this endpoint. For longer history, build your own persistence layer that polls this endpoint and writes to your store.

3.2 noti_types allowed values

Value	Meaning
stock	Equity-level alert
news	News-driven
earnings	Earnings event
dividends	Dividend event
splits	Stock split
option_contract	Option contract event
price_target	Analyst price target change
analyst_rating	Analyst rating change
option_contract_interval	Interval-based option contract event
insider_trades	Form 4 insider transaction
trading_state	Trading halt / resume / LULD
fda	FDA event
economic_release	Macro release (CPI, FOMC, NFP, …)
politician_trades	Congressional trade disclosure
market_tide	Market-wide flow tide signal
sec_filings	SEC filing match
flow_alerts	Options flow alert
chain_oi_change	Option chain OI change
gex	GEX-level alert

3.3 Response schema (per alert)

Field	Type	Description
id	string (UUID)	Alert firing ID
created_at	string (ISO 8601)	When the alert was created in UW’s system
tape_time	string (ISO 8601)	When the underlying market event occurred
name	string	Human-readable alert name (from the config)
noti_type	string	One of the values in 3.2
symbol	string	Affected symbol (ticker, option occ, etc.)
symbol_type	string	Symbol class
meta	object	Raw alert payload (shape varies by noti_type)
user_noti_config_id	string (UUID)	Pointer to the config that produced this firing

The meta object’s shape is variable - parse it per noti_type. Schema your way out of this with discriminated-union types (pydantic Tagged Unions, or a dict + per-type adapter).

3.4 MK3 use

The flow_alerts, chain_oi_change, gex, and market_tide notification types are the strategy-relevant ones. Workflow:

1. Set up named configurations in UW’s web UI (or via a future POST config endpoint if one exists).
2. Poll GET /api/alerts with intraday_only=true, noti_types[]=flow_alerts,gex,chain_oi_change,market_tide, ticker_symbols=SPY.
3. Stream the results onto Nautilus’s MessageBus as a UWAlert custom-data type with a noti_type-discriminated meta.
4. Strategies subscribe and react.

The 14-day window is fine for live; for backtest replay we need our own historical alert store (see 2026-05-15-mk3-data-foundation-constraint).

4. GET /api/alerts/configuration - Alert configs

Returns the saved alert rules behind the firings in endpoint #1.

4.1 Query parameters

None documented.

4.2 Response schema (per config)

Field	Type	Description
id	string	Config ID (matches user_noti_config_id on firings)
name	string	Config name
noti_type	string	One of the values in 3.2
status	string	E.g. active, paused
created_at	string (ISO 8601)	When the config was saved
mobile_only	bool	If true, alert only fires to mobile (skip via API workflows)
config	object	The rule body. Shape varies by noti_type.

The config object’s structure is variable. Example types from the docs:

• An chain_oi_change config carries the OI delta threshold + the filter (ticker, side, dte, …).
• A sec_filings config carries the filing-text search term (e.g. "berkshire").

4.3 MK3 use

Read-only at MK3 scope. Two uses:

1. Reconciliation: when an alert fires, look up its config to know the exact rule that triggered. Helpful for postmortems (“why did this fire on a non-trend day?”).
2. Inventory: confirm the expected MK3 set of configs exists on the account (we may want to assert a baseline set of flow_alerts, gex, and market_tide rules are active).

Mobile-only configs are excluded from the API alert feed by UW’s backend. If a config is mobile_only: true, it won’t show up in endpoint #1 - useful when reconciling “why am I not seeing this firing in my Nautilus stream?“

5. Nautilus integration shape

Same pattern as uw-api-gex-greeks:

1. Custom data class: UWAlert (and a per-noti_type discriminated meta).
2. Polling Actor: UWAlertsActor polls /api/alerts every N seconds (15s? 30s? rate-limit-bound), de-duplicates by id, publishes new firings to the bus.
3. Optional config snapshot: one-time GET /api/alerts/configuration at session start, cached in memory for reconciliation.
4. Strategy subscribers: react to specific noti_type topics.

Per nautilus-dev-adapters this is a thin REST adapter - simpler than a streaming venue, but still goes through Codex for authoring.

6. Known gaps

• No POST/PUT/DELETE for configs. Reading-only. Configs are created and edited in UW’s web UI (or a separate mutable endpoint not in this set).
• No WebSocket push for alerts. Polling only via this surface.
• 14-day historical window on /api/alerts. Build local persistence for longer history.
• Variable meta and config shapes. Cataloging the per-type payloads is a future page (concepts/uw-alert-payload-schemas).

7. Source URLs (verbatim, for re-fetch)

• https://api.unusualwhales.com/docs/operations/PublicApi.AlertsController.alerts
• https://api.unusualwhales.com/docs/operations/PublicApi.AlertsController.configs

uw-api-gex-greeks 2026-05-15-mk3-setup-hunter-architecture 2026-05-15-mk3-data-foundation-constraint nautilus-dev-adapters nautilus-custom-data