Unusual Whales API - Short endpoints (ShortController)

Unusual Whales API - Short endpoints

Layer mapping: L2 / L3. Short data is fundamentally a per-ticker positioning signal that compounds over days to weeks. Not useful for 0DTE SPY L1 because:

1. SPY itself has stable, low short interest (broadly held ETF).
2. Short-squeeze dynamics don’t apply to ETFs.
3. SEC FTD data carries a regulatory 2-week reporting lag.

Where it matters: L2 swing-trade plays on individual constituents (esp. mid-cap squeeze candidates) and L3 longer-horizon positioning themes. Filed for future per cortana-north-star.

Seven endpoints, all under ShortController. One cross-ticker screener plus six per-ticker views.

1. Base contract

Property	Value
Base URL	https://api.unusualwhales.com
Auth	Authorization: Bearer <token> header
Response envelope	{ "data": [...] } or { "data": {...} }
Status codes	200, 422, 500
Regulatory lag	FTDs ~14 days; short interest reported bi-monthly

2. Endpoint matrix

#	Path	Purpose
1	GET /api/short_screener	Cross-ticker short screen (borrow metrics)
2	GET /api/shorts/{ticker}	Per-ticker short data history
3	GET /api/shorts/{ticker}/ftds	SEC failures to deliver (~14-day lag)
4	GET /api/shorts/{ticker}/interest-float	Short interest + float (v1)
5	GET /api/shorts/{ticker}/interest-float/v2	Improved variant (v2)
6	GET /api/shorts/{ticker}/volume-and-ratio	Daily short volume + ratio
7	GET /api/shorts/{ticker}/volume-by-exchange	Short volume split by venue

3. GET /api/short_screener - Cross-ticker screener

Find tickers matching short-related filter criteria.

Query parameters:

Param	Type	Default	Notes
tickers	string	-	Comma-separated; - to exclude
limit	int	100	0-500
offset	int	0	>= 0
min/max_short_interest	number	-	Absolute share count
min/max_days_to_cover	number	-	Days needed to cover at current volume
min/max_si_float	number	-	Short interest / float ratio
min/max_si_float_with_synth_long_pct_of_total_shares	number	-	With synthetic long adjustment
min/max_total_float	number	-	Float share count
min/max_fee_rate	number	-	Borrow fee rate (annualized)
min/max_rebate_rate	number	-	Borrow rebate rate
min/max_short_shares_available	number	-	Available to borrow
min/max_market_date	date	-	Date range filter
order_by	enum	-	market_date, etc.
order_direction	enum	desc	asc or desc

Response per record:

Field	Type	Description
symbol	string	Ticker
short_interest	int	Shares sold short
days_to_cover	string	Decimal days
si_float	string	SI / float ratio (decimal)
si_float_with_synth_long_pct_of_total_shares	string	Adjusted
total_float	int	Float
fee_rate	(date - likely a typo for decimal)	Borrow fee
rebate_rate	(date - likely typo for decimal)	Borrow rebate
short_shares_available	(date - likely typo for int)	Available
market_date	date	Snapshot date

Note: docs list fee_rate, rebate_rate, and short_shares_available as date type which is almost certainly a documentation bug (they should be decimal and int respectively). Verify on first fetch.

Use: screen for squeeze candidates (high SI/float, low days-to-cover, high fee rate, low short_shares_available). L2 strategy fodder.

4. GET /api/shorts/{ticker} - Per-ticker short data

Daily short-related metrics for one ticker.

Path: ticker.

Response per record (inferred from sibling endpoints): daily timeseries with short interest, ratio, borrow rates, FTD context.

5. GET /api/shorts/{ticker}/ftds - Failures to deliver

SEC regulatory failure-to-deliver data.

Path: ticker.

Response per record:

Field	Type	Description
date	date	FTD reporting date
price	string	Close price on date
quantity	string	Shares that failed to deliver

Critical caveat from UW docs: “SEC FTD data is typically 2 weeks delayed.” This is regulatory; no workaround. Means: not for realtime / intraday use ever.

Use: L3 only. Persistent high FTDs can signal manipulation (naked shorting) or distribution stress. Long-horizon only.

6. GET /api/shorts/{ticker}/interest-float (v1)

Short interest reported vs total float, time series.

Response (inferred): per reporting cycle (FINRA reports bi-monthly), short interest absolute + as % of float.

Use: the canonical short-interest measure. Bi-monthly cadence limits its utility for anything faster than weekly strategies.

7. GET /api/shorts/{ticker}/interest-float/v2

Improved variant. Per UW versioning convention, v2 likely adds synthetic-long adjustment or finer-grained reporting.

Always prefer v2 for new code.

8. GET /api/shorts/{ticker}/volume-and-ratio

Daily short volume + short volume ratio.

Path: ticker.

Response per record:

Field	Type	Description
market_date	date	Trading date
close_price	string	Close
short_volume	int	Shares sold short that day
total_volume	int	Total daily volume
short_volume_ratio	string (decimal)	short_volume / total_volume

Note: this is off-exchange short volume reported daily, NOT short interest. Different metric. Daily-fresh (unlike bi-monthly short interest).

Use: the most actionable short metric. High daily short volume ratio = lots of new selling pressure today. L2 useful for swing-trade exit timing.

9. GET /api/shorts/{ticker}/volume-by-exchange

Short volume split by venue (NASDAQ, NYSE, etc.).

Path: ticker.

Response (inferred): per-exchange breakdown of daily short volume.

Use: venue-specific analysis. If most shorting is happening on one exchange, it might indicate single-actor dominance.

10. MK3 use

Not in current scope. Filed for L2 / L3 future work.

For SPY hunter specifically: SPY’s short interest is ~0.5%-1.5% of float and changes very slowly. There’s no actionable L1 signal here.

For L2 mag7 constituent strategies: NVDA, TSLA, and other high-beta mega-caps periodically see meaningful short-interest spikes. The contrarian-aggressor finding (2026-05-22-uw-historical-findings) applies to options flow, not equity short positioning - they’re different signals.

11. Nautilus integration shape (when L2/L3 lands)

• Daily polling Actor: UWShortActor pulls /shorts/{ticker}/volume-and-ratio end-of-day for the watchlist.
• Weekly polling for short-interest endpoints (v2 only).
• FTD data: weekly polling, treat as positioning context not signal.

12. Known gaps / footguns

• Several fields documented as date type that are clearly decimal or int. First fetch needs to confirm actual types.
• /short_screener response schema shows data as object, not array - probably wraps one screener result. Verify.
• Short interest reports bi-monthly by regulators. Don’t expect daily freshness from interest-float endpoints.
• FTD ~14-day lag is regulatory and unfixable.
• No options-related short data here. Equity-only.

13. Source URLs

• https://api.unusualwhales.com/docs/operations/PublicApi.ShortController.short_screener
• https://api.unusualwhales.com/docs/operations/PublicApi.ShortController.short_data
• https://api.unusualwhales.com/docs/operations/PublicApi.ShortController.failures_to_deliver
• https://api.unusualwhales.com/docs/operations/PublicApi.ShortController.short_interest_and_float
• https://api.unusualwhales.com/docs/operations/PublicApi.ShortController.short_interest_and_float_v2
• https://api.unusualwhales.com/docs/operations/PublicApi.ShortController.short_volume_and_ratio
• https://api.unusualwhales.com/docs/operations/PublicApi.ShortController.short_volume_by_exchange

cortana-north-star uw-api-darkpool uw-api-lit-flow uw-api-screener