Unusual Whales API - Screener endpoints
Layer mapping: mixed.
/screener/option-contracts(Contract Screener) - L1 partial. Programmatic candidate discovery on the option-chain dimension. Use to find unusual SPY contracts without polling the whole chain./screener/stocks(Stock Screener) - L1 partial. Find tickers meeting criteria (e.g. mag7 with elevated IV rank). For SPY hunter, used as a constituent monitoring tool./screener/analyst-ratings- L2. Per-ticker analyst rating changes for swing-trade context.
Three endpoints, very wide filter sets. The contract screener has 60+ parameters - the most expressive query surface in the API.
1. Base contract
| Property | Value |
|---|---|
| Base URL | https://api.unusualwhales.com |
| Auth | Authorization: Bearer <token> header |
| Response envelope | { "data": [...] } |
| Status codes | 200, 422, 500 |
2. Endpoint matrix
| # | Path | Purpose | Layer |
|---|---|---|---|
| 1 | GET /api/screener/option-contracts | Screen option contracts (60+ filters) | L1 |
| 2 | GET /api/screener/stocks | Screen stocks by options activity + fundamentals | L1 |
| 3 | GET /api/screener/analyst-ratings | Recent analyst rating changes feed | L2 |
3. GET /api/screener/option-contracts - Contract screener
The most expressive endpoint in the API. 60+ filter parameters spanning underlying, strikes, expiry, volume, OI, Greeks, IV, price changes, OI trends, fundamentals, and trade-type ratios.
3.1 Filter categories
| Category | Representative parameters |
|---|---|
| Underlying + contract | ticker_symbol, type (call/put), is_otm, is_new, opex_only |
| Price + strike | min/max_underlying_price, min/max_strike, min/max_close, min/max_diff, min/max_premium, min/max_avg_price |
| Expiration + earnings | min/max_dte, min/max_earnings_dte, min/max_days_between_expiry_and_earnings, expiry_dates[], exclude_ex_div_ticker |
| Volume + OI | min/max_volume, min/max_open_interest, vol_greater_oi, min/max_volume_oi_ratio, min/max_floor_volume, min/max_floor_volume_ratio, min/max_multileg_volume_ratio, min/max_ticker_30d_avg_volume, min/max_contract_30d_avg_volume, min/max_volume_ticker_vol_ratio, min/max_sweep_volume_ratio |
| Greeks + IV | min/max_delta (-1 to 1), min/max_gamma (0+), min/max_theta (-inf to 0), min/max_vega (0+), min/max_iv_perc |
| Price changes | min/max_perc_change, min/max_daily_perc_change, min/max_from_low_perc, min/max_from_high_perc |
| Side + sentiment | min/max_bid_perc, min/max_ask_perc, min/max_skew_perc, min/max_bull_perc, min/max_bear_perc, min/max_bid_side_perc_7_day, min/max_ask_side_perc_7_day |
| OI trends | min/max_days_of_oi_increases, min/max_days_of_vol_greater_than_oi, min/max_oi_change_perc, min/max_oi_change |
| Fundamentals | sectors[] (11 GICS), min/max_marketcap, issue_types[] (Common Stock, ETF, Index, ADR), min/max_return_on_capital_perc |
| Counts | min/max_transactions |
| Sorting + pagination | order (25+ sort keys), order_direction, limit (1-250, default 50), page, date |
3.2 Response per contract
| Field | Type | Description |
|---|---|---|
option_symbol | string | OCC symbol |
volume, open_interest | int | Contract counts |
ask_side_volume, bid_side_volume, mid_volume, no_side_volume, cross_volume | int | Side breakdown |
floor_volume, sweep_volume, multileg_volume, stock_multi_leg_volume | int | Trade-type breakdown |
open, high, low, close, chain_prev_close, avg_price | string | OHLC + averages |
last_fill | ISO 8601 | Last fill timestamp |
premium | string | $ premium |
stock_price | string | Underlying price |
ticker_vol | int | Underlying stock volume |
sector | string | Underlying sector |
next_earnings_date, er_time | string | Earnings context |
trades | int | Trade count |
total_ask_changes, total_bid_changes | int | Quote-change counts |
3.3 MK3 use (L1)
The contract screener replaces full-chain polling for SPY 0DTE discovery. Example queries:
A. Find unusual SPY 0DTE call activity:
GET /api/screener/option-contracts?
ticker_symbol=SPY&
type=call&
max_dte=0&
vol_greater_oi=true&
min_volume_oi_ratio=2&
min_premium=50000&
order=premium&
order_direction=desc&
limit=20
B. Find OTM 0DTE ask-side accumulation candidates (fade candidates per 2026-05-22-uw-historical-findings):
GET /api/screener/option-contracts?
ticker_symbol=SPY&
type=call&
is_otm=true&
max_dte=0&
min_ask_perc=0.7&
min_premium=25000&
order=ask_side_volume&
order_direction=desc
The screener is what makes the contrarian-aggressor strategy actionable - it lets you identify the exact contracts where the fade pattern is forming, in real time.
4. GET /api/screener/stocks - Stock screener
Cross-ticker screen by options activity + fundamentals + IV.
4.1 Filter categories
| Category | Representative parameters |
|---|---|
| Identification | ticker, issue_types[], is_s_p_500, has_dividends, sectors[] |
| Price + change | min/max_change, min/max_underlying_price |
| Marketcap | min/max_marketcap |
| Options volume ratios | min/max_perc_3_day_total/call/put, min/max_perc_30_day_* |
| OI changes | min/max_total/call/put_oi_change_perc |
| Implied move | min/max_implied_move, min/max_implied_move_perc |
| Volatility | min/max_volatility, min/max_iv_rank |
| Volume + OI | min/max_volume, min/max_call_volume, min/max_put_volume, min/max_oi, min/max_oi_vs_vol |
| Premium | min/max_premium, min/max_call_premium, min/max_put_premium, net variants |
| P/C ratio | min/max_put_call_ratio |
| Stock volume vs avg | min_stock_volume_vs_avg30_volume, max_avg30_volume |
| Sorting + pagination | order (40+ keys), order_direction, date |
4.2 Response per stock
Returns: ticker, close, prev_close, implied_move + percent, call_volume / put_volume, call_open_interest / put_open_interest, call_premium / put_premium, bullish_premium / bearish_premium, net_call_premium / net_put_premium, put_call_ratio, iv30d (+ 1d/1w/1m deltas), iv_rank, volatility, marketcap, sector, issue_type, week_52_high / week_52_low, next_earnings_date, er_time, next_dividend_date, is_index, avg_3_day_call_volume, avg_30_day_call_volume, prev_call_oi / prev_put_oi, relative_volume.
4.3 MK3 use (L1)
For SPY hunter, the stock screener is a constituent monitor. Examples:
A. Find mag7 names with elevated IV rank (volatility regime divergence):
GET /api/screener/stocks?
ticker=AAPL,MSFT,NVDA,AMZN,META,GOOGL,GOOG&
order=iv_rank&
order_direction=desc
B. Find S&P 500 names with anomalous options activity today:
GET /api/screener/stocks?
is_s_p_500=true&
min_perc_3_day_total=2.0&
min_premium=1000000&
order=relative_volume&
order_direction=desc&
limit=20
Compare results with SPY’s top-25 holdings (uw-api-etfs /holdings)
to know which big SPY weights are seeing flow today. The output feeds
into the SPY-implied flow tape feature.
5. GET /api/screener/analyst-ratings - L2
Recent analyst rating changes feed.
Query parameters (inferred): ticker, start_date, end_date,
min_action_type (upgrade / downgrade / initiate / reiterate),
limit, page.
Response per record: ticker, analyst, action, prior_rating, new_rating, prior_target, new_target, published_at, source.
Use: L2 swing-trade context only. Not in MK3 scope. Filed for future per cortana-north-star.
6. Nautilus integration shape (L1 only)
| Endpoint | Cadence | Notes |
|---|---|---|
/screener/option-contracts | On demand, per query | The “find me” interface; called by signal Actors when they need a candidate list |
/screener/stocks | Every 5-15 min during RTH | Constituent monitor - watch top-25 SPY weights |
/screener/analyst-ratings | Not wired | L2 only |
The contract screener replaces the per-contract polling pattern in
uw-api-option-contract for cases where you don’t know which
contracts to watch yet. Once a contract is identified, switch to
uw-api-option-contract /flow for per-trade detail.
7. Known gaps
- Analyst ratings response schema not fully fetched. L2 fodder.
orderenum on contract screener has 25+ values - cataloging the most useful sorts is a future task.- No
min_ask_premium/min_bid_premiumseparation on the stock screener - only aggregatemin_premium. - Rate limits unknown on screener endpoints. With 60+ filters and 250-record pages, abuse is possible.
8. Source URLs
https://api.unusualwhales.com/docs/operations/PublicApi.ScreenerController.contract_screenerhttps://api.unusualwhales.com/docs/operations/PublicApi.ScreenerController.stock_screenerhttps://api.unusualwhales.com/docs/operations/PublicApi.ScreenerController.analyst_ratings
cortana-north-star uw-api-option-contract uw-api-option-trade uw-api-etfs 2026-05-22-uw-historical-findings 2026-05-15-mk3-setup-hunter-architecture