Unusual Whales API - Ticker Meta + Underlying endpoints
Layer mapping: mixed. Seven endpoints under TickerController
that cover the per-ticker metadata and underlying-equity surface
(not options). Plus per-ticker rollups of insider and ownership data
that overlap with the dedicated uw-api-insiders and
uw-api-institutional controllers.
1. Endpoint matrix
| # | Path | Purpose | Layer |
|---|---|---|---|
| 1 | GET /api/stock/{ticker}/info | Ticker info / metadata | L1 (reference) |
| 2 | GET /api/stock/{ticker}/companies-in-sector | Sector peers of the ticker | L2 (reference) |
| 3 | GET /api/stock/{ticker}/ohlc/{candle_size} | OHLC bars at chosen size | L1 (price data) |
| 4 | GET /api/stock/{ticker}/last-stock-state | Last price / state snapshot | L1 (reference) |
| 5 | GET /api/stock/{ticker}/stock-volume-price-level | Volume at price (underlying) | L1 (volume profile) |
| 6 | GET /api/stock/{ticker}/insider-buy-sell | Per-ticker insider rollup | L3 |
| 7 | GET /api/stock/{ticker}/ownership | Per-ticker institutional ownership | L3 |
2. 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 |
3. GET /api/stock/{ticker}/info
Per-ticker metadata.
Path: ticker.
Response (inferred): ticker, name, sector, industry,
country, marketcap, next_earnings_date, er_time,
next_dividend_date, is_index, is_s_p_500, has_options.
Use: session-start one-shot. Cache per-ticker for the day.
4. GET /api/stock/{ticker}/companies-in-sector
List of companies in the same sector as the given ticker.
Use: L2 reference for sector-rotation strategies. For SPY hunter specifically, not load-bearing (SPY’s “sector” is ETF, not a GICS sector).
5. GET /api/stock/{ticker}/ohlc/{candle_size} (LOAD-BEARING for backtest)
OHLC bars at the chosen candle size.
Path parameters:
| Param | Required | Values |
|---|---|---|
ticker | yes | Stock symbol |
candle_size | yes | E.g. 1m, 5m, 15m, 30m, 1h, 1d (verify on first fetch) |
Query parameters (inferred): date_from, date_to, limit.
Response per bar (inferred): timestamp, open, high, low,
close, volume.
Use (L1, load-bearing for backtest): SPY’s underlying price candles. The replay backbone for any backtest. Pair with uw-api-ticker-flow minute-level flow per strike to build aligned historical bars + flow.
6. GET /api/stock/{ticker}/last-stock-state
Last-known underlying state.
Response (inferred): ticker, last_price, bid, ask,
volume, timestamp.
Use: sanity-check current price during runtime. Not the primary price feed - that should come from Nautilus’s own data engine (IBKR market data).
7. GET /api/stock/{ticker}/stock-volume-price-level
Volume-at-price distribution for the underlying.
Response (inferred): [{price_level, volume}].
Use: volume profile / market-profile analysis. Useful for identifying VWAP, point-of-control, and high-volume nodes - all classical day-trading levels. Lower priority for SPY hunter than flow + max pain + OI levels, but a viable secondary input.
8. GET /api/stock/{ticker}/insider-buy-sell
Per-ticker insider buy/sell rollup.
Layer: L3. Same data as uw-api-insiders /sector-flow and
/{ticker}/{type}-flow, ticker-scoped. Filed for future L3.
Use: L3 only. Not in MK3 scope.
9. GET /api/stock/{ticker}/ownership
Per-ticker institutional ownership rollup.
Layer: L3. Same data as uw-api-institutional /{ticker}/ownership
(probably literally the same endpoint with different routing). Filed
for future L3.
Use: L3 only. SPY’s institutional ownership is too broad to extract L1 signal.
10. MK3 use
| Endpoint | Cadence | L1? |
|---|---|---|
/info | Session start | Yes (reference) |
/companies-in-sector | Not wired | No |
/ohlc/{size} | Backtest replay + session-start lookback | Yes (backtest backbone) |
/last-stock-state | On demand (sanity check) | Yes (reference) |
/stock-volume-price-level | Session start (yesterday’s profile) | Optional |
/insider-buy-sell | Not wired | No |
/ownership | Not wired | No |
11. Nautilus integration shape
UWTickerInfo(one-shot at session start) for/info.UWUnderlyingBarfor/ohlc/{size}- either custom data or use Nautilus’s standard Bar type and adapt.UWLastStockStatefor/last-stock-state- probably unused if IBKR is the primary price source.- Per-ticker insider + ownership: not wired at MK3 scope; future L3.
12. Known gaps
- Several response schemas inferred - first fetches confirm.
/ohlccandle_size enum - not documented; assumed standard values./ownershipvs uw-api-institutional/ownership- data overlap; confirm which is canonical on first fetch./last-stock-statefreshness - how stale is “last”? Verify; IBKR is the primary price source for live trading anyway.
13. Source URLs
https://api.unusualwhales.com/docs/operations/PublicApi.TickerController.infohttps://api.unusualwhales.com/docs/operations/PublicApi.TickerController.companies_in_sectorhttps://api.unusualwhales.com/docs/operations/PublicApi.TickerController.ohlchttps://api.unusualwhales.com/docs/operations/PublicApi.TickerController.last_stock_statehttps://api.unusualwhales.com/docs/operations/PublicApi.TickerController.stock_volume_price_levelhttps://api.unusualwhales.com/docs/operations/PublicApi.TickerController.insider_buy_sellhttps://api.unusualwhales.com/docs/operations/PublicApi.TickerController.ownership
cortana-north-star uw-api-insiders uw-api-institutional uw-api-ticker-flow uw-api-ticker-iv-greeks uw-api-ticker-positioning