Unusual Whales API - News endpoints (NewsController)

Unusual Whales API - News endpoints

Layer mapping: L1 partial / L2.

• major_only=true filter → L1 partial. Tier-1 macro / market- wide headlines (Fed, geopolitics, mega-cap earnings surprises) that move SPY.
• ticker=X filter → L2. Per-ticker news flow for swing-trade strategies.

One endpoint, broad coverage. Single most-likely source of “out-of- band” market shocks - Fed pivots, geopolitical events, mega-cap guidance pre-announcements.

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

2. Endpoint

GET /api/news/headlines

Time-windowed feed of news headlines with sentiment classification.

Query parameters:

Param	Type	Required	Default	Range	Notes
sources	string	no	-	-	Comma-separated source names (e.g. BusinessWire,MarketNews)
search_term	string	no	-	-	Keyword filter in headline text
ticker	string	no	-	-	Filter to one symbol
major_only	bool	no	false	-	Restrict to significant events only
limit	int	no	50	1 to 100
page	int	no	0	-	Pagination

Response per record:

Field	Type	Description
created_at	ISO 8601	Publication timestamp
headline	string	Headline text
source	string	Publishing outlet
tickers	array	Associated symbols
tags	array	Topic / category labels
sentiment	string	positive, negative, or neutral
is_major	bool	Significance flag
meta	object	Source-specific extras

The tags taxonomy isn’t enumerated in the docs - expect things like earnings, fda, m_and_a, fed, geopolitics, analyst, guidance. Catalog on first real fetch.

3. MK3 use

3.1 L1 (SPY hunter)

Pre-classifier filter: poll with major_only=true every 30s.

Derived features:

Feature	Definition
is_major_news_event_in_last_5min	bool
major_news_in_5min_sentiment_balance	sum of (+1 positive, -1 negative, 0 neutral) over last 5 min
fed_news_in_session	bool, did a tags ~ fed major headline drop today
geopolitical_news_in_session	bool

Strategy gate: if is_major_news_event_in_last_5min AND the headline mentions Fed / Trump / geopolitical / mega-cap-guidance, suspend new entries for 5 minutes while the tape repositions.

This is a circuit-breaker style use, not an alpha signal. News moves the tape unpredictably; the right response is to step back, not to scalp the headline.

3.2 L2 (per-ticker NLP)

For swing strategies, the per-ticker news stream + sentiment is the signal substrate. Polling ticker=AAPL and rolling sentiment over a rolling 7-day window builds the swing-trade context. Filed for L2, not in MK3 scope.

4. Nautilus integration shape

• UWNewsActor polls /api/news/headlines?major_only=true every 30s. De-dupes by (created_at, headline).
• Publishes UWNewsHeadline custom data to the bus.
• A circuit-breaker Actor consumes and sets a news_event_active flag for the next 5 min after any major headline.

5. Source-quality notes

The sources parameter accepts a curated list. Tier-1 sources (typically): Bloomberg, Reuters, BusinessWire, PRNewswire, AP. Lower-tier: aggregators, blog reposts. Verify the source taxonomy on first fetch - the docs don’t enumerate the full set.

For L1 circuit-breaker use, only trust Bloomberg/Reuters/BW/PRN. Sentiment classification on a low-tier source is noisier than the benefit.

6. Known gaps

• Sentiment quality. UW’s sentiment classifier methodology isn’t documented. Could be straight LLM, could be sentence-level dictionary, could be combined. Treat as “directional hint, not ground truth.”
• is_major threshold opaque. Bool flag but the trigger criteria aren’t published.
• No tags taxonomy in the docs.
• No realtime push. Polling only - latency to print is poll-interval bounded (worst case 30s late on a market-moving headline).
• No source whitelist enforcement on response. If you don’t pass sources=, you get the full firehose including low-quality aggregators.

7. Source URL

• https://api.unusualwhales.com/docs/operations/PublicApi.NewsController.headlines

cortana-north-star uw-api-alerts uw-api-economy uw-api-earnings 2026-05-15-mk3-setup-hunter-architecture