Unusual Whales API - Group Flow endpoints (GroupFlowController)

Unusual Whales API - Group Flow endpoints

Layer mapping: L1 partial. The mag7, technology, semi, and communication services groups are direct context for SPY (top weights live in these). Other sector groups (uranium, gold, REIT, airline, etc.) are L2 fodder for swing strategies on those sectors.

Two endpoints. Same Greek-flow shape as the ticker-level uw-api-gex-greeks family 2, but aggregated across a sector / thematic group instead of one symbol.

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
Numeric format	Strings (parse to float)

2. Endpoint matrix

#	Path	Purpose
1	GET /api/group-flow/{flow_group}/greek-flow	Aggregate Greek flow for a sector/group
2	GET /api/group-flow/{flow_group}/greek-flow/{expiry}	Same, filtered to one expiration date

3. The flow_group taxonomy

Valid path values (sector / thematic classifications):

airline, bank, basic materials, china, communication services, consumer cyclical, consumer defensive, crypto, cyber, energy, financial services, gas, gold, healthcare, industrials, mag7, oil, real estate, refiners, reit, semi, silver, technology, uranium, utilities.

L1 relevance ranking (for SPY hunter):

Group	Why it matters for SPY
mag7	Top-7 SPY constituents (~30%+ weight). Direct proxy for SPY mega-cap flow.
technology	~30% of SPY by weight. Driver of recent regime.
semi	NVDA + AVGO are huge SPY weights; semi-specific flow context.
communication services	META + GOOG + GOOGL = ~7% of SPY.
financial services / bank	~13% of SPY; useful but secondary.
consumer cyclical / consumer defensive	Sector breadth checks.
healthcare	~13% of SPY.
All others	L2/L3 fodder. Not in MK3 scope.

URL-encode group names with spaces: consumer%20defensive.

4. GET /api/group-flow/{flow_group}/greek-flow

Aggregate flow for the group.

Path parameter: flow_group (required, see taxonomy above).

Query parameters:

Param	Type	Required	Default
date	date	no	last trading date

Response per row:

Field	Type	Description
flow_group	string	Echo of group name
timestamp	ISO 8601	Aggregation timestamp
transactions	int	Total trade count in group
volume	int	Total option volume
net_call_premium	string	Net call $ premium (buy - sell)
net_call_volume	int	Net call contracts
net_put_premium	string	Net put $ premium
net_put_volume	int	Net put contracts
total_delta_flow	string	Sum
total_vega_flow	string	Sum
dir_delta_flow	string	Directional (signed)
dir_vega_flow	string	Directional (signed)
otm_total_delta_flow	string	OTM-only total
otm_total_vega_flow	string	OTM-only total
otm_dir_delta_flow	string	OTM-only directional
otm_dir_vega_flow	string	OTM-only directional

5. GET /api/group-flow/{flow_group}/greek-flow/{expiry}

Same fields, filtered to one expiry.

Path parameters: flow_group + expiry (ISO date).

Query parameters: date (last trading date default).

Use: for 0DTE SPY work, fetch mag7 flow filtered to today’s expiry to see how the mega-caps are positioning specifically for the end-of-day.

6. MK3 use (L1)

Cadence: every minute during RTH for mag7, technology, semi, communication services. Daily cache for the others.

Derived feature ideas:

Feature	Definition
mag7_net_call_premium_1m_zscore	z-score vs 60-min trailing mean
mag7_dir_delta_flow_sign	sign of dir_delta_flow
mag7_otm_call_dominance	otm_dir_delta_flow > 0 AND net_call_premium > N * net_put_premium
breadth_tech_vs_consumer	tech vs consumer cyclical/defensive divergence
sector_flow_dispersion	std-dev of dir_delta_flow across SPY-relevant groups

Critical interaction with 2026-05-22-uw-historical-findings. The contrarian-aggressor finding (OTM call-buying predicts SPY DOWN) applies to ticker-level flow. Whether the same flip holds at the sector/group level is untested in the corpus - the historical findings were per-ticker. Before using mag7_otm_call_dominance as a contrarian signal, run the same analysis on group-flow data.

7. Nautilus integration shape

• Custom data class: UWGroupFlowSnapshot.
• Polling Actor: UWGroupFlowActor polls the 4 L1-relevant groups every minute. Lower priority groups (sectors) poll once per 5-min or skip entirely.
• Publishes one snapshot per group per minute to the bus.
• A signal Actor computes derived breadth + dispersion features.

8. Known gaps

• No per-group flow at the ticker level inside a group. This is pre-aggregated. To know whether mag7 flow is AAPL-driven vs NVDA-driven, fall back to per-ticker uw-api-gex-greeks.
• flow_group taxonomy is fixed - no custom group definition.
• Spaces in group names require URL encoding.
• Contrarian-flip applicability untested at the group level.

9. Source URLs

• https://api.unusualwhales.com/docs/operations/PublicApi.GroupFlowController.greek_flow
• https://api.unusualwhales.com/docs/operations/PublicApi.GroupFlowController.greek_flow_expiry

cortana-north-star uw-api-gex-greeks uw-api-etfs 2026-05-22-uw-historical-findings 2026-05-15-mk3-setup-hunter-architecture