/api/v1/tickers/{ticker}/holdersTop institutional holders across ALL 9,600+ 13F filers with quarter-over-quarter change.
Top institutional holders across ALL 9,600+ 13F filers with quarter-over-quarter change. Queries form_13f_holdings directly (not just tracked funds). CUSIP successor chain expansion and amendment deduplication included. Returns status (New/Increased/Decreased/Unchanged/Closed) and change % vs previous quarter.
Top institutional holders for a ticker across ALL 9,600+ 13F filers (post-v3.3.0 rewrite — the legacy implementation was limited to the 668-fund tracked subset). Each holder row carries QoQ change in shares and a status classification (New / Increased / Decreased / Unchanged / Closed) so portfolio managers can spot smart-money rotation at a glance. CUSIP successor-chain expansion preserves M&A continuity (e.g. PFE/Wyeth merger, GOOGL share-class restructuring); amendment deduplication ensures one row per (CIK × period) pair. NOT-split-adjusted shares preserve the as-filed view — for split-adjusted historical aggregations use GET /api/v1/tickers/{ticker}/fund-trends. Pair with GET /api/v1/tickers/{ticker}/overview for the comprehensive company-overview view, GET /api/v1/13dg/holders/{ticker} for the activist-shareholder sibling (5%+ beneficial owners filing 13D/G), and GET /insider-module/api/insiders/transactions/by-ticker for the Form 4 insider-activity sibling.
Parameters
| Name | In | Required | Default | Allowed | Description | Example |
|---|---|---|---|---|---|---|
| ticker | path | required | — | — | Ticker symbol (canonical hyphen form). Server normalizes case + dot/slash variants. Multi-class issuers preserve the requested class. CUSIP successor chain is automatically expanded — for Alphabet (`GOOGL` / `GOOG`) returns positions across pre/post-2014-share-class-restructuring CUSIPs. | AAPL |
| limit | query | optional | 100 | — | Max funds per page (default 100, max 500). For typical UI tables 20-50; for full-list export 500 + paginated walks. | 20 |
| offset | query | optional | 0 | — | Skip first N results for pagination (default 0). Use with `limit` to page through all holders. For tickers with 4000+ holders (mega-caps), 80+ paginated calls would be needed for full enumeration; use `POST /api/v1/form-13f/holdings` for bulk-export workflows. | 0 |
| status | query | optional | all | — | Filter by QoQ status: `all` (default), `new` (just-opened positions), `increased` (added shares), `decreased` (trimmed shares), `unchanged` (held flat), `closed` (just-exited positions). For smart-money-momentum dashboards use `new` + `increased`; for distribution dashboards use `decreased` + `closed`. | increased |
| period | query | optional | — | — | Specific report period (ISO `YYYY-MM-DD` quarter-end format like `2025-09-30`). Defaults to latest available period (typically the quarter ending 45-90 days ago given the SEC 45-day filing deadline + ETL lag). | 2025-09-30 |
| quarters | query | optional | 1 | — | Number of quarters to return (default 1, max 20). When `>1`, response includes a `quarters[]` array with per-quarter holders and QoQ changes — useful for trend charts. When `1`, response is the flat single-period view shown in the sample. | 4 |
Response schema
| Field | Type | Nullable | Description |
|---|---|---|---|
| status | string | no | — |
| request_id | string | yes | — |
| timestamp | string | no | — |
| data | object | no | One quarter uses holders and totals directly. quarters>1 returns quarters[], ticker, cusips and available_quarters instead. Empty results use the single-quarter shape without pagination fields. |
| data.period | string | yes | Optional; omitted when not applicable. |
| data.prev_period | string | yes | Optional; omitted when not applicable. |
| data.holders | array | no | Optional; omitted when not applicable. |
| data.holders[].cik | string | no | — |
| data.holders[].name | string | no | — |
| data.holders[].shares | number | no | — |
| data.holders[].value | number | no | — |
| data.holders[].prev_shares | number | no | — |
| data.holders[].chg_pct | number | yes | — |
| data.holders[].status | string | no | — |
| data.total_shares | number | no | Optional; omitted when not applicable. |
| data.total_value | number | no | Optional; omitted when not applicable. |
| data.total_holders | integer | no | Optional; omitted when not applicable. |
| data.total_count | integer | no | Optional; omitted when not applicable. |
| data.offset | integer | no | Optional; omitted when not applicable. |
| data.limit | integer | no | Optional; omitted when not applicable. |
| data.security_name | string | yes | — |
| data.ticker | string | no | Optional; omitted when not applicable. |
| data.cusips | array | no | Optional; omitted when not applicable. |
| data.cusips[] | string | no | — |
| data.quarters | array | no | Optional; omitted when not applicable. |
| data.quarters[].period | string | yes | — |
| data.quarters[].prev_period | string | yes | — |
| data.quarters[].holders | array | no | — |
| data.quarters[].holders[].cik | string | no | — |
| data.quarters[].holders[].name | string | no | — |
| data.quarters[].holders[].shares | number | no | — |
| data.quarters[].holders[].value | number | no | — |
| data.quarters[].holders[].prev_shares | number | no | — |
| data.quarters[].holders[].chg_pct | number | yes | — |
| data.quarters[].holders[].status | string | no | — |
| data.quarters[].total_shares | number | no | — |
| data.quarters[].total_value | number | no | — |
| data.quarters[].total_holders | integer | no | — |
| data.quarters[].total_count | integer | no | Optional; omitted when not applicable. |
| data.quarters[].offset | integer | no | Optional; omitted when not applicable. |
| data.quarters[].limit | integer | no | Optional; omitted when not applicable. |
| data.available_quarters | array | no | Optional; omitted when not applicable. |
| data.available_quarters[] | string | no | — |
Sample response
- "status": "success"
- "request_id": null
- "timestamp": "2026-09-25T12:00:00Z"
- "data":
- "holders":
- "period": "2026-06-30"
- "prev_period": "2026-03-31"
- "total_shares": 100
- "total_value": 20000
- "total_holders": 1
- "total_count": 1
- "offset": 0
- "limit": 100
- "security_name": "APPLE INC"
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/tickers/AAPL/holders?limit=20&offset=0&status=increased&period=2025-09-30&quarters=4" \
-H "X-API-Key: YOUR_API_KEY"Generate an API key in /account/credentials to run live queries (literal YOUR_API_KEY placeholder shown until then).