Unusual Whales API - Earnings endpoints (EarningsController)

Unusual Whales API - Earnings endpoints

Layer mapping:

• /api/earnings/afterhours + /api/earnings/premarket → L1 partially (SPY doesn’t report, but mega-caps in SPY do, and their postmarket/premarket prints drive SPY gaps).
• /api/earnings/{ticker} → L2 (per-ticker swing-trade context).

SPY itself never appears in these feeds. What matters for L1 is who in SPY is reporting tonight or tomorrow morning. AAPL after the bell can move SPY 50 bps overnight.

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 matrix

#	Path	Purpose	Layer
1	GET /api/earnings/afterhours	Tickers reporting after the bell	L1 (calendar)
2	GET /api/earnings/premarket	Tickers reporting before the open	L1 (calendar)
3	GET /api/earnings/{ticker}	Historical earnings reactions for one ticker	L2

3. GET /api/earnings/afterhours

Tickers scheduled to report after market close.

Query parameters:

Param	Type	Required	Default	Range
date	date	no	last trading date	-
limit	int	no	50	1 to 100
page	int	no	-	starts at 0

Response per record:

Field	Type	Description
symbol	string	Ticker
full_name	string	Legal company name
report_date	ISO date	Earnings report date
report_time	string	E.g. "postmarket", "premarket"
ending_fiscal_quarter	ISO date	Quarter end
street_mean_est	string	Analyst consensus EPS
actual_eps	string	Reported EPS (post-report only)
pre_earnings_close	string	Close before report
pre_earnings_date	ISO date	Date of pre_earnings_close
post_earnings_close	string	Close after report
post_earnings_date	ISO date	Date of post_earnings_close
reaction	string	Stock reaction (numeric %, as string)
expected_move	string	Implied dollar move
expected_move_perc	string	Implied % move
marketcap	string	Market cap
is_s_p_500	bool	S&P 500 membership
sector	string	GICS sector
continent, country_code, country_name	strings	Geography
has_options	bool	Options trade for ticker
source	string	Data source attribution

4. GET /api/earnings/premarket

Same schema as #3, filtered to tickers reporting before the open.

Query parameters: identical to #3 (date, limit, page).

5. GET /api/earnings/{ticker}

Historical earnings reactions for one ticker. Different schema - adds straddle returns and pre/post-event move statistics.

Path parameter: ticker (required, e.g. AAPL)

Query parameters: none documented.

Response per record:

Field	Description
report_date, report_time	When the earnings dropped
ending_fiscal_quarter	Quarter end
actual_eps, street_mean_est	EPS + consensus
expected_move, expected_move_perc	Implied move at report
pre_earnings_move_1d, _3d, _1w, _2w	Moves into earnings
post_earnings_move_1d, _3d, _1w, _2w	Moves out of earnings
long_straddle_1d, _1w	Long straddle return at exit
short_straddle_1d, _1w	Short straddle return at exit
source	Data origin

All numeric values returned as strings.

6. MK3 use

6.1 L1 (SPY hunter)

Pre-session routine, every trading day:

1. Pull /api/earnings/afterhours for today’s date - list of mega-caps reporting tonight.
2. Pull /api/earnings/premarket for tomorrow’s date - list of mega-caps reporting before open.
3. Filter to is_s_p_500: true and top weights (combine with uw-api-etfs/weights for SPY: cross-reference symbols against SPY’s top-25 weight constituents).
4. Build a gap-risk feature: n_mega_cap_earnings_overnight. Tradeoff: high overnight earnings density = higher overnight gap risk for SPY = bias L1 to either flatten EOD or sit on hands.
5. Day-of-week awareness: mega-cap earnings cluster (AAPL + AMZN + GOOG on a Thursday, for example). Don’t sleep through it.

6.2 L2 (out of MK3 scope)

/api/earnings/{ticker} is the per-ticker historical reaction. For swing-trade strategy on individual names, it’s the core feed. Not relevant to MK3 right now - filed for future L2 work.

Per cortana-north-star section 6 (scope discipline): the per-ticker historical reaction data is L2 fodder. Don’t wire it into MK3.

7. Nautilus integration shape (L1 only)

• One-time pull at session start of /afterhours (today) + /premarket (tomorrow).
• Cache in memory.
• Publish a UWEarningsCalendar snapshot to the bus once.
• Strategies subscribe and read at decision time, never poll repeatedly.

No per-record custom data needed - just a daily snapshot type.

8. Known gaps

• reaction is a string-typed number - parse to float.
• The straddle returns in /earnings/{ticker} are not labeled with long-vs-short clearly until you look at the full field names. Code defensively.
• No futures-impact field (e.g. /ES overnight move into earnings).
• No earnings whisper number; just consensus.

9. Source URLs

• https://api.unusualwhales.com/docs/operations/PublicApi.EarningsController.afterhours
• https://api.unusualwhales.com/docs/operations/PublicApi.EarningsController.premarket
• https://api.unusualwhales.com/docs/operations/PublicApi.EarningsController.ticker

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