/api/v1/form-13f/market-rotationInstitutional rotation between value and growth and between cyclical and defensive sector buckets, computed from reporter-comparable sector flow.
Institutional rotation between value and growth and between cyclical and defensive sector buckets, computed from reporter-comparable sector flow. Overall and per-bucket comparison coverage is returned; ratios are null and signals are Indeterminate when a required flow is unavailable.
free
Why use this
Macro rotation rollup over the sector summary. Current ownership values remain complete, while flows and ratios preserve unavailable comparison states instead of converting them to zero.
Common use case
Building a macro rotation dashboard: 'Is institutional money rotating from growth to value this quarter?' Use ?compare=prev to see the shift between quarters, e.g., 'Q3 was Strong Growth Rotation but Q4 shifted to Strong Value Rotation'. Combine with sector drill-down from /aggregation/by-sector for full picture.
Macro rotation signals derived from reporter-comparable sector flow. Each constituent sector, each macro bucket, and the overall result carries comparison coverage. If a required bucket has no usable comparison, its flow and dependent ratio remain null and the signal is Indeterminate; a measured zero remains zero. Optional previous-quarter comparison also returns that quarter's coverage, preventing a shift from being inferred across unavailable data. Bucket membership, thresholds, current ownership values, filing metadata, and endpoint parameters are unchanged.
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 | yes | Comparable value-bucket flow divided by comparable growth-bucket flow. Null when either required flow is unavailable or the denominator is zero. |
| data.value_growth_signal | string | no | Rotation label derived from value_growth_ratio; Indeterminate when the ratio is null. |
| data.cyclical_defensive_ratio | number | yes | Comparable cyclical-bucket flow divided by comparable defensive-bucket flow. Null when either required flow is unavailable or the denominator is zero. |
| data.cyclical_defensive_signal | string | no | Rotation label derived from cyclical_defensive_ratio; Indeterminate when the ratio is null. |
| data.comparison_position_count | integer | yes | Usable comparisons rolled across all sector rows. |
| data.comparison_unavailable_count | integer | yes | Unavailable comparisons rolled across all sector rows. |
| data.comparison_status | string | yes | Overall complete, partial, unavailable, or legacy-unknown comparison coverage. |
| data.total_value_flow | number | yes | Comparable net flow for the value bucket. |
| data.total_growth_flow | number | yes | Comparable net flow for the growth bucket. |
| data.total_cyclical_flow | number | yes | Comparable net flow for the cyclical bucket. |
| data.total_defensive_flow | number | yes | Comparable net flow for the defensive bucket. |
| data.bucket_comparison | object | no | Coverage for each value, growth, cyclical, and defensive bucket; each contains comparison_position_count, comparison_unavailable_count, and comparison_status. |
| data.sector_buckets | object | no | Four arrays named value, growth, cyclical, and defensive. Each array contains constituent sector rows with nullable comparable fund_flow, current total_value, flow significance, momentum label, and comparison coverage. |
| data.sector_buckets.value | array | no | Value-sector detail rows for Financial Services, Energy, Utilities, Basic Materials, and Real Estate. Each row carries nullable comparable flow, current value, and comparison coverage. |
| data.sector_buckets.growth | array | no | Growth-sector detail rows for Technology, Communication Services, Consumer Discretionary, and Healthcare, with the same shape as the value array. |
| data.sector_buckets.cyclical | array | no | Cyclical-sector detail rows for Consumer Discretionary, Financial Services, Industrials, Basic Materials, and Energy, with the same shape as the value array. |
| data.sector_buckets.defensive | array | no | Defensive-sector detail rows for Consumer Staples, Healthcare, Utilities, and Communication Services, with the same shape as the value array. |
| data.comparison | object | yes | Returned as data.comparison when compare=prev. It contains prior ratios and signals, prior comparison coverage and bucket coverage, nullable ratio changes, and signal shifts. |
| 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"
- "comparison_position_count": 220000
- "comparison_unavailable_count": 0
- "comparison_status": "complete"
- "total_value_flow": 150000000
- "total_growth_flow": 210000000
- "sector_buckets":
- "bucket_comparison":
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?quarter=2025Q4&compare=false" \
-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).