/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.
5 tokensSince v1.0.0
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 |
|---|---|---|---|
| data.ticker | string | no | Ticker echoed back in canonical hyphen form. |
| data.period | string | no | ISO `YYYY-MM-DD` quarter-end date for the snapshot. Always 03-31 / 06-30 / 09-30 / 12-31. The 13F filing for this period was due 45 days later. Most-recent quarter may be partially populated during the 45-day filing window — see `/form-13f/filing-progress` for completeness gauge. |
| data.prev_period | string | yes | ISO `YYYY-MM-DD` quarter-end of the prior quarter (used as the baseline for QoQ `chg_*` and `status` fields). Null when `period` is the earliest covered quarter. |
| data.holders[] | array | no | Array of holder rows, sorted by `value DESC` (largest position first). Up to `limit` rows; total set has `total_count` rows. Empty array for tickers no fund has ever held (most pre-IPO and very-thinly-held names). |
| data.holders[].cik | string | no | Filer CIK in 10-char zero-padded form (e.g. `0001067983` for Berkshire Hathaway, `0001364742` for BlackRock, `0000884144` for Vanguard, `0001037389` for Renaissance Technologies). Use as join key against `/api/v1/form-13f/fund/{cik}` for the per-fund detail view. |
| data.holders[].name | string | no | Filer name as registered with SEC EDGAR (typically all-caps EDGAR convention). Use for human-readable holder labels. |
| data.holders[].shares | number | no | Share count for the position as of `period`. NOT split-adjusted server-side (preserves the as-filed view) — for split-adjusted historical aggregations use [GET /api/v1/tickers/{ticker}/fund-trends](/docs/company-data/ticker-research/get-tickers-ticker-fund-trends). |
| data.holders[].value | number | no | Position value (USD) at the period-end mark-to-market price. Post-Plan-51 holdings-quality value normalization (handles the pre-Q3-2022 thousands-vs-actual-dollars SEC reporting issue) — for historical filings the parser auto-detected and corrected the unit on a per-filing basis. Always presented in actual USD here. |
| data.holders[].pct_of_portfolio | number | yes | Position weight in the holder's total portfolio (decimal — `0.255` = 25.5%). Useful for ranking holders by conviction (a fund with 25% portfolio weight has higher relative conviction than one with 0.5%). Null for filers without a complete portfolio for the quarter (rare). |
| data.holders[].chg_shares | number | yes | QoQ share-count change vs `prev_period` (signed integer). Positive = added; negative = trimmed. Null when prior-quarter baseline is missing (new positions show null, not zero — disambiguates 'new buy' from 'held flat at zero'). |
| data.holders[].chg_pct | number | yes | QoQ percent change in shares (decimal — `-0.250` = -25%). Null for new positions (no prior baseline to divide by). For mass-comparison use `status` instead — handles the null-case cleanly. |
| data.holders[].status | string | no | QoQ status classification: `New` (no position in `prev_period`), `Increased` (added shares), `Decreased` (trimmed shares), `Unchanged` (held flat), `Closed` (had position in `prev_period`, zero in `period`). Use for status-filtered holder tables and smart-money-momentum dashboards. |
| data.holders[].accession_number | string | yes | SEC accession number for the 13F filing this row was extracted from (18-char dashed format like `0000950123-25-009876`). Useful for audit-trail UIs and EDGAR-link generation. Null for amendment-superseded rows where only the amendment's accession is preserved. |
| data.holders[].filed_at | string | no | ISO `YYYY-MM-DD` date the 13F was filed with SEC EDGAR. Always within 45 days of `period`. |
| data.total_shares | number | no | Aggregate institutional share count across ALL holders (not just the paginated subset). NOT split-adjusted — for split-adjusted historical totals use `/tickers/{ticker}/fund-trends`. |
| data.total_value | number | no | Aggregate institutional position USD value across all holders. Post-Plan-51 normalized. |
| data.total_holders | integer | no | Distinct holder CIK count for the ticker in `period`. Mega-caps (AAPL, MSFT) typically 4000-5000; small-caps 50-300; micro-caps 1-30. |
| data.total_count | integer | no | Total holder rows matching the `status` filter (= `total_holders` when `status=all`). Use for pagination math. |
| data.offset | integer | no | Echoed-back pagination offset. |
| data.limit | integer | no | Echoed-back page-size limit. |
Sample response
·
- "data":
- "ticker": "AAPL"
- "period": "2025-09-30"
- "prev_period": "2025-06-30"
- "holders":
- "total_shares": 8920000000
- "total_value": 2326200000000
- "total_holders": 4775
- "total_count": 4775
- "offset": 0
- "limit": 100
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/{ticker}/holders?api_Token=YOUR_API_KEY" \
-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).