Unusual Whales API - Institutional endpoints (InstitutionController)

Unusual Whales API - Institutional endpoints

Layer mapping: L3 only. All 6 endpoints serve 13F-derived institutional positioning data, which is quarterly with a 45-day filing lag. The cadence is fundamentally wrong for L1 0DTE. Filed for L3 trend / sector-rotation work per cortana-north-star.

Six endpoints: per-institution activity, per-institution holdings, per-institution sector breakdown, per-ticker ownership, institution list, and the latest-filings feed.

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
Cadence	Quarterly (13F filings) with 45-day lag

2. Endpoint matrix

#	Path	Purpose
1	GET /api/institution/{name}/activity/v2	Per-institution transaction history (v2 schema)
2	GET /api/institution/{name}/holdings	Per-institution current holdings
3	GET /api/institution/{name}/sectors	Per-institution sector allocation
4	GET /api/institution/{ticker}/ownership	Per-ticker institutional ownership list (inverse)
5	GET /api/institutions	List of tracked institutions
6	GET /api/institutions/latest-filings	Cross-institution latest filings feed

Convention: the path segment {name} is the institution identifier (CIK or name); {ticker} is the equity symbol. Mixing them up returns 422.

3. GET /api/institution/{name}/activity/v2

Per-institution position changes between 13F filings.

Path parameter:

Param	Required	Notes
name	yes	Institution name or CIK (e.g. "VANGUARD GROUP INC" or "0000102909")

Query parameters:

Param	Type	Required	Default	Max
ticker_symbol	string	no	-	Comma-separated; prefix - to exclude
start_date	date	no	-	-
end_date	date	no	-	-
limit	int	no	500	500
page	int	no	-	-
order	enum	no	units	units or units_change
order_direction	enum	no	desc	desc or asc

Response per record:

Field	Type	Description
ticker	string	Symbol held
units	int	Shares held as of report_date
units_change	int	Change from prior filing (signed)
report_date	ISO date	13F reporting date (quarter end)
filing_date	ISO date	Actual SEC filing date
avg_price	string	Average price during period
buy_price	string / null	Inferred average buy price
sell_price	string / null	Inferred average sell price
close	string	Close on filing date
price_on_filing	string	Price on filing date
price_on_report	string	Price on report date
put_call	string / null	Option side if applicable
security_type	string	E.g. "stock", "call", "put"
shares_outstanding	string	Float at report date

Cadence: quarterly. Q1 reports file in mid-May, Q2 in mid-August, Q3 in mid-November, Q4 in mid-February.

4. GET /api/institution/{name}/holdings

Per-institution current holdings (the inventory).

Query parameters: similar filter set (ticker_symbol, security_types[], sorting by units or value, pagination).

Response: current snapshot of the institution’s positions as of the most recent 13F.

5. GET /api/institution/{name}/sectors

Per-institution sector allocation rollup.

Response: sector-by-sector breakdown showing what % of the institution’s portfolio is in each GICS sector.

Use: at a glance, “is Vanguard overweight Tech?“. Useful for constructing benchmark-tracking analyses.

6. GET /api/institution/{ticker}/ownership

Inverse lookup: which institutions own this ticker.

Path: ticker = equity symbol (not institution).

Response per record: institution name, units held, units change, report date, percent of float. Multiple institutions per ticker.

Use: “who holds AAPL?“. For L3 sector-rotation strategies, track which top holders are accumulating vs distributing.

7. GET /api/institutions

Roster of tracked institutions.

Query parameters: filters by name, CIK, AUM range. Pagination.

Response per record: institution name, CIK, AUM, filing frequency, latest filing date.

Use: discovery + watchlist construction. Find the 50 largest institutional shareholders of major US equities.

8. GET /api/institutions/latest-filings

Cross-institution feed of newest 13F filings.

Query parameters: date filters, pagination.

Response per record: institution + filing date + summary stats on the filing (number of positions, total AUM, top buys/sells).

Use: event detection. When a new high-profile filing drops (Berkshire, ARK, Pershing Square), trigger downstream L3 analysis.

9. MK3 use

Not in current scope. Quarterly cadence with 45-day filing lag.

L3 strategy possibilities (future):

• “Smart-money basket” tracking: pick 10-20 institutions with documented above-market returns, track aggregate accumulation / distribution per ticker, build a long-horizon tilt.
• Crowding detection: when too many top institutions hold the same name, fade the consensus.
• New-money inflection: institution that wasn’t in the name last quarter just took a 1%+ position. Stronger signal than incremental position changes from existing holders.

For L1 SPY hunter, none of this is operative. SPY’s institutional ownership is so broad (~9000 funds hold it) that the signal-to-noise on quarterly changes is functionally zero.

10. Nautilus integration shape (when L3 lands)

• Quarterly polling Actor: UWInstitutionalActor runs on filing windows (mid-May, mid-Aug, mid-Nov, mid-Feb).
• Snapshots cached to Postgres for historical lookback.
• L3 Strategies query the snapshot at decision time, not realtime.

11. Known gaps

• 45-day filing lag is regulatory. Cannot work around.
• 13F covers long equity + listed options only. Short positions, swaps, OTC derivatives, fixed income are NOT in 13F. Major blind spot for hedge funds with significant short books.
• avg_price, buy_price, sell_price are inferred, not reported. Treat as estimates.
• {name} accepting both name AND CIK is convenient but error-prone - if a name has multiple matches in UW’s DB (e.g. “VANGUARD” matching multiple registered entities), behavior is undocumented. Prefer CIK.

12. Source URLs

• https://api.unusualwhales.com/docs/operations/PublicApi.InstitutionController.activity_v2
• https://api.unusualwhales.com/docs/operations/PublicApi.InstitutionController.holdings
• https://api.unusualwhales.com/docs/operations/PublicApi.InstitutionController.sectors
• https://api.unusualwhales.com/docs/operations/PublicApi.InstitutionController.ownership
• https://api.unusualwhales.com/docs/operations/PublicApi.InstitutionController.list
• https://api.unusualwhales.com/docs/operations/PublicApi.InstitutionController.latest_filings

cortana-north-star uw-api-insiders uw-api-congress