Unusual Whales API - Insider endpoints (InsiderController)

Unusual Whales API - Insider endpoints

Layer mapping: L3 only. Form 4 insider transactions (corporate officers + 10%-owner shareholders) carry a multi-day to multi-month signal horizon. Filing lag is 2 business days post-trade. Wrong cadence for 0DTE; filed for future L3 work per cortana-north-star.

Four endpoints: transactions feed, by-sector flow, insider roster, per-ticker flow.

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
1	GET /api/insider/transactions	Cross-ticker recent Form 4 transactions
2	GET /api/insider/sector-flow	Daily sector-rollups of insider buying/selling
3	GET /api/insider/{ticker}/{type}-flow	Per-ticker rollups (or /insiders for an inventory)
4	GET /api/insider/{ticker}/insiders	Roster of insiders + their stake history for a ticker

(Endpoint #3 and #4 share the same {ticker} path-scoped prefix but differ in trailing segment.)

3. GET /api/insider/transactions

Cross-ticker Form 4 feed.

Query parameters:

Param	Type	Required	Default	Notes
ticker_symbol	string	no	-	Comma-separated; prefix - to exclude
start_date	date	no	-
end_date	date	no	-
limit	int	no	500	Max 500
page	int	no	-	Starts at 0
min_amount	int	no	0	Min transaction notional
max_amount	int	no	-
txn_codes	array	no	-	Filter by code (e.g. P, S, A)
insider_relationships	array	no	-	Filter by role

Form 4 transaction codes (txn_codes):

Code	Meaning
P	Open-market purchase (strongest bullish signal)
S	Open-market sale
A	Award / grant (compensation, not a discretionary trade)
M	Exercise of derivative security
F	Payment of exercise / tax (forced sell)
D	Disposition of derivative
G	Gift
J	Other
V	Reported voluntarily early

For signal: filter to P (purchases) and S (sales) only. Awards (A), tax-payment sales (F), and gifts (G) carry no discretionary information.

Response per record: transaction details, insider name + role, ticker, transaction code, share count, price, dollar amount, filing date, reporting date.

4. GET /api/insider/sector-flow

Daily sector rollups of insider activity.

Query parameters:

Param	Type	Required	Default
date	date	no	last trading date

Response per sector: sector name, total buy $,totalsell$, net $, transaction count, distinct insider count.

Use: macro-level insider sentiment. “Insiders in Technology bought $X net last week” is a weekly-to-monthly signal.

5. GET /api/insider/{ticker}/{type}-flow

Per-ticker rollup of buy or sell activity. The type path segment toggles between buy and sell.

Path parameters:

Param	Required	Notes
ticker	yes	Stock symbol
type	yes	buy or sell

Query parameters:

Param	Type	Required	Default
start_date	date	no	-
end_date	date	no	-
limit	int	no	500
page	int	no	-

Use: drill into one ticker’s insider history. Useful for L2 or L3 postmortems (“did the CFO sell ahead of this print?“).

6. GET /api/insider/{ticker}/insiders

Roster of insiders for a ticker with stake history.

Path parameter: ticker (required).

Response per record: insider name, role/title, total shares held, last reported date, transaction history.

Use: know the cast. For L3 strategies that filter on “high-conviction insiders” (e.g. CEO with multi-year track record), this builds the watchlist.

7. MK3 use

Not in current scope. Filed for L3. The signal horizon (Form 4 takes 2 days to file; alpha decays over weeks not minutes) is wrong for 0DTE.

Future L3 strategies built on this surface:

• Cluster buy detection: 3+ insiders at the same firm buying in the same week. Historically the most reliable insider signal.
• CEO/CFO concentration: weight by role; CEO/CFO trades > VP trades > Director trades.
• Anti-leakage: track unusual insider sales in the 30 days before known catalysts (earnings, FDA dates, M&A rumors).

8. Nautilus integration shape (when L3 lands)

• Daily polling Actor: UWInsiderActor pulls /api/insider/transactions with start_date=T-7.
• Publishes UWInsiderTransaction custom data to the bus.
• A L3 Strategy aggregates with multi-day windows.

9. Known gaps

• No real-time push. Polling only.
• Filing lag is 2 business days minimum (regulatory).
• insider_relationships taxonomy not documented - first fetch needs to catalog.
• No 10b5-1 plan flag in the documented schema. Pre-scheduled sales (10b5-1) carry less signal than discretionary sales.

10. Source URLs

• https://api.unusualwhales.com/docs/operations/PublicApi.InsiderController.transactions
• https://api.unusualwhales.com/docs/operations/PublicApi.InsiderController.sector_flow
• https://api.unusualwhales.com/docs/operations/PublicApi.InsiderController.insiders
• https://api.unusualwhales.com/docs/operations/PublicApi.InsiderController.ticker_flow

cortana-north-star uw-api-congress uw-api-institutional