/api/v1/form-13f/market-rotationDetect institutional rotation between value/growth and cyclical/defensive sector buckets.
Detect institutional rotation between value/growth and cyclical/defensive sector buckets. Computes flow ratios from pre-aggregated sector-level 13F data and classifies rotation strength into 5 tiers (Strong/Moderate Value or Growth, Balanced). Supports quarter-over-quarter comparison to track rotation shifts. Response includes quarter_metadata (quarter, filing_deadline, is_complete, days_until_deadline) indicating whether the quarter's data is complete or still accumulating.
Why use this
Common use case
Computes institutional rotation signals between value/growth and cyclical/defensive sector buckets — the macro-tier complement to GET /api/v1/form-13f/aggregation/by-sector. Read-time computation from sec_13f_sector_summary (no precompute layer needed — the sector-level aggregate is already small enough to roll up into bucket ratios in <50ms).
Designed for the 'portfolio managers tracking sector rotation across institutional holders' persona — answers 'Is institutional money rotating from growth to value this quarter?' (value/growth ratio) and 'Are institutions positioning risk-on or risk-off?' (cyclical/defensive ratio). Use ?compare=prev to surface QoQ rotation SHIFTS — the most signal-rich case is a cross-tier shift like 'Strong Growth -> Moderate Value', indicating a regime change in institutional positioning.
Bucket definitions (from macro-finance literature):
- Value: Financials, Healthcare, Energy, Utilities
- Growth: Technology, Consumer Cyclical, Communication Services, Real Estate
- Cyclical: Consumer Cyclical, Technology, Industrials, Basic Materials, Energy
- Defensive: Utilities, Healthcare, Consumer Defensive, Communication Services
Note that Technology, Consumer Cyclical, and Communication Services appear in multiple buckets — this multi-classification is intentional (per industry convention). Combine with GET /api/v1/form-13f/aggregation/by-sector for sector-level drill-down WITHIN a bucket once the rotation signal is identified at the macro tier. All monetary values are in USD (post-Plan-51 thousands correction).
Cost: heavy quant endpoint — derives from sector-summary materialized view, but the bucket-rollup math + 5-tier classification is read-time. Filed under heavy-ops because it's typically called alongside /aggregation/by-sector and /fund-performance for full macro-rotation dashboards.
Parameters
| Name | In | Required | Default | Allowed | Description | Example |
|---|---|---|---|---|---|---|
| quarter | query | optional | — | — | Quarter end date YYYY-MM-DD (e.g. 2025-12-31). Defaults to latest available. | 2025Q4 |
| compare | query | optional | — | — | Set to 'prev' to include QoQ comparison with previous quarter. Shows rotation shift (e.g., 'Strong Growth -> Moderate Value'). | false |
Response schema
| Field | Type | Nullable | Description |
|---|---|---|---|
| status | string | no | Always `success` on a 2xx response. Custom envelope (not the standard `ApiResponse`) — `data` carries the four headline ratios + four sector buckets directly. |
| data.quarter | string | no | ISO `YYYY-MM-DD` reporting quarter — always a calendar quarter end. Echoed from the request; defaults to the latest available quarter. |
| data.value_growth_ratio | number | no | Ratio = `value_bucket_total_flow / growth_bucket_total_flow`. Values >1 indicate rotation INTO value (institutions favoring Financials/Healthcare/Energy/Utilities); values <1 indicate rotation INTO growth (favoring Technology/Consumer Cyclical/Communication Services/Real Estate). 5-tier classification surfaced in `value_growth_signal`. |
| data.value_growth_signal | string | no | 5-tier rotation classification derived from `value_growth_ratio`: `Strong Value Rotation` (ratio ≥2), `Moderate Value Rotation` (≥1.3), `Balanced` (0.77-1.3), `Moderate Growth Rotation` (≥0.5), `Strong Growth Rotation` (<0.5). The single most-used field for macro-rotation dashboards. |
| data.cyclical_defensive_ratio | number | no | Ratio = `cyclical_bucket_total_flow / defensive_bucket_total_flow`. Cyclical bucket = Consumer Cyclical, Technology, Industrials, Basic Materials, Energy (sectors that benefit from economic expansion). Defensive bucket = Utilities, Healthcare, Consumer Defensive, Communication Services (sectors that hold up in downturns). Values >1 indicate rotation INTO cyclicals (risk-on); values <1 indicate rotation INTO defensives (risk-off / recession-positioning). |
| data.cyclical_defensive_signal | string | no | 5-tier rotation classification derived from `cyclical_defensive_ratio`: `Strong Cyclical Rotation` (≥2), `Moderate Cyclical Rotation` (≥1.3), `Balanced` (0.77-1.3), `Moderate Defensive Rotation` (≥0.5), `Strong Defensive Rotation` (<0.5). Useful for macro-positioning context (risk-on vs risk-off institutional posture). |
| data.sector_buckets | object | no | Per-bucket breakdown: `{ value: {total_flow, sectors[]}, growth: {...}, cyclical: {...}, defensive: {...} }`. Each bucket lists the constituent sectors with their individual `fund_flow` and `total_value` — useful for understanding which sectors are driving the rotation signal. |
| data.sector_buckets.value | object | no | Value bucket: Financials, Healthcare, Energy, Utilities. Shape: `{ total_flow, sectors: [{ sector, fund_flow, total_value }, ...] }`. `total_flow` is the sum of constituent `fund_flow` values (USD, post-Plan-51 thousands correction). |
| data.sector_buckets.growth | object | no | Growth bucket: Technology, Consumer Cyclical, Communication Services, Real Estate. Same shape as `value` bucket. Tech sector typically dominates this bucket's flow. |
| data.sector_buckets.cyclical | object | no | Cyclical bucket: Consumer Cyclical, Technology, Industrials, Basic Materials, Energy. Note: Technology and Consumer Cyclical appear in BOTH growth and cyclical buckets — this is intentional (multi-classification per macro literature). |
| data.sector_buckets.defensive | object | no | Defensive bucket: Utilities, Healthcare, Consumer Defensive, Communication Services. Same multi-classification overlap with growth bucket on Communication Services. |
| data.compare | object | yes | QoQ comparison block — present ONLY when `?compare=prev`. Shape: `{ value_growth_shift: 'Moderate Growth -> Strong Value', cyclical_defensive_shift: 'Balanced -> Moderate Cyclical', value_growth_ratio_change: -0.18, cyclical_defensive_ratio_change: 0.42 }`. The string-encoded `*_shift` fields are designed for direct UI rendering ('Q3 was Strong Growth Rotation but Q4 shifted to Strong Value Rotation'). |
| data.quarter_metadata | object | no | Filing-completeness state for the quarter: `{ quarter, filing_deadline, is_complete, days_until_deadline }`. Same shape as [GET /api/v1/form-13f/filing-progress](/docs/institutional-holdings/filing-progress-tracking/get-form-13f-filing-progress). `is_complete=false` during filing season — gate downstream rotation analysis until the quarter has matured (sparse early-season data can produce misleading rotation signals). |
Sample response
- "status": "success"
- "data":
- "quarter": "2025-12-31"
- "value_growth_ratio": 0.71
- "value_growth_signal": "Moderate Growth Rotation"
- "cyclical_defensive_ratio": 2.14
- "cyclical_defensive_signal": "Strong Cyclical Rotation"
- "sector_buckets":
Errors
| Status | Label | Description |
|---|---|---|
| 200 | OK | Request succeeded. |
| 400 | Bad Request | Invalid query, body, or path parameter. |
| 401 | Unauthorized | Missing or invalid Authorization header / api_Token. |
| 402 | Payment Required | Insufficient token balance for this call. Top up |
| 429 | Too Many Requests | Rate limit exceeded for your tier (see /pricing for tier limits). Tier limits |
| 500 | Server Error | Unexpected server-side failure. Retry with backoff; report if persistent. |
Code samples
curl "https://api.finradar.ai/api/v1/form-13f/market-rotation" \
-H "Authorization: Bearer YOUR_JWT_TOKEN"Generate an API key in /account/credentials to run live queries (literal YOUR_API_KEY placeholder shown until then).