/api/v1/form-13f/holdingsSearch raw 13F holdings grouped by filing using Lucene-like query syntax.
Search raw 13F holdings grouped by filing using Lucene-like query syntax.
10 tokensSince v1.0.0
Why use this
The headline analytics endpoint of FinRadar's institutional-holdings module — query any combination of CIK, date range, ticker, or CUSIP across 8M+ raw 13F holdings rows. Returns per-filing position rows (NOT pre-aggregated) with full voting authority, investment discretion, and put/call data preserved as filed. The bread-and-butter workflow for hedge-fund whale-watching: pass `cik:1067983 AND periodOfReport:2025-12-31` to get Berkshire Hathaway's Q4 2025 book exactly as filed. Pass `includeChanges=true` to also receive QoQ deltas (`changeShares`, `changePercent`, `status`, `previousPeriod`, `closedPositions`) — critical for momentum-detection workflows. Ticker/CUSIP queries auto-expand through CUSIP successor chains so a query for `holdings.ticker:GOOGL` will correctly capture the position even after Alphabet's 2014 share-class restructuring. Value-correction metadata (`valueCorrected`, `correctionMethod`, `originalValueTotal`) is included on every row to flag the 13F thousands-vs-actual-dollars reporting issue (Plan 51 holdings-quality layer). For lighter cover-page-only queries use `POST /api/v1/form-13f/cover-pages`.
Common use case
Retrieve Berkshire Hathaway's exact holdings as filed for Q3 2024, including share counts, voting authority, and CUSIP-level detail. Useful for regulatory analysis, filing-level audits, and replicating sec-api.io queries.
Returns position-level 13F holdings for a filer — the headline analytics endpoint of the institutional-holdings module. Pass cik + optional period to get one quarter; pass includeChanges=true (v3.2.0) to also receive QoQ deltas (changeShares, changePercent, status, previousPeriod, closedPositions). Holdings are deduplicated to one row per CUSIP per filing — amendments collapse to the latest. CIK normalization handles the 6/7/10-char zero-padding inconsistency automatically. Pair with POST /api/v1/form-13f/cover-pages for filing-metadata-only lookups.
Parameters
| Name | In | Required | Default | Allowed | Description | Example |
|---|---|---|---|---|---|---|
| query | body | required | — | — | Lucene-like query string. Field-scoped: `cik:1067983` (filer CIK, with or without zero-padding), `periodOfReport:2024-09-30` (exact quarter end), `periodOfReport:[2024-01-01 TO 2024-12-31]` (range), `filedAt:[A TO B]` (filing date range), `formType:"13F-HR"`, `holdings.ticker:AAPL` (chain-aware), `holdings.cusip:037833100` (chain-aware), `accessionNo:0001067983-24-000123`. Combine with `AND`/`OR`/`NOT`. Bare-word queries are matched against issuer name. | cik:1067983 AND periodOfReport:2025-12-31 |
| from | body | optional | 0 | — | Zero-based pagination offset (NUMBER of filings to skip — NOT a date despite the name). Increment by `size` to walk pages: `from=0` → page 1, `from=50` → page 2 (when `size=50`). Capped at 10000 server-side; for deeper backfills use date-range chunking via `periodOfReport:[A TO B]`. | 0 |
| size | body | optional | 50 | — | Number of filings (NOT individual holdings rows) to return per page, capped at 50 server-side. Each filing can carry 1-3000+ holdings rows so total payload size scales with `size × avg_holdings_per_filing`. For Berkshire-shaped books expect ~50 holdings per filing; for index-fund books (Vanguard, BlackRock) expect ~3000+. | 50 |
| sort | body | optional | — | — | Sort specification array (sec-api.io shape). Each element is `{ <field>: { order: 'asc' | 'desc' } }`. Common: `[{"filedAt": {"order": "desc"}}]` (most recent first), `[{"periodOfReport": {"order": "asc"}}]` (chronological for time-series). Defaults to `filedAt DESC` when omitted. | [{"filedAt": {"order": "desc"}}] |
| includeChanges | body | optional | false | — | When `true` AND `holdings.ticker` is set in the query, adds QoQ change fields to each ticker-matching holding: `changeShares` (int), `changePercent` (float), `status` (`New`/`Increased`/`Decreased`/`Unchanged`/`Closed`). Also returns `closedPositions` array (positions present in prior quarter but absent now) and `previousPeriod` (quarter used for comparison). Uses canonical CUSIP matching via `cusip_normalized` so cross-quarter corporate actions (mergers, ticker changes, share-class collapses) are correctly tracked. ~30-50% latency overhead per call. | true |
Response schema
| Field | Type | Nullable | Description |
|---|---|---|---|
| cik | string | no | Filer CIK as a 10-character zero-padded string. Echoed back from the request — useful for asserting your client passed the CIK you intended after the server's CIK-padding normalization (handles 6/7/10-char input forms). |
| period | string | no | ISO `YYYY-MM-DD` reporting period end (always a calendar quarter end: 03-31, 06-30, 09-30, 12-31). The 13F is filed within 45 days of this date — for delivery tracking against the 45-day deadline, see `/api/v1/form-13f/filing-progress`. |
| holdings | array | no | Array of position rows in the filing — one row per CUSIP. Amendments collapse to the latest filing per `(cik, period)` (so a 13F-HR/A overrides the original 13F-HR). Sorted by `value_usd DESC` by default. Empty array on legitimate empty filings (rare but valid for 13F-HR/A amendments that zero out a previously-reported holding). |
| holdings[].cusip | string | no | 9-character CUSIP as filed. The natural primary key for the position. Note: filers occasionally report 8-char CUSIPs (missing check digit) — these are zero-padded server-side. For chain-aware queries (CUSIP successor mappings across mergers), use the `holdings.cusip:` query syntax which auto-expands the chain. |
| holdings[].ticker | string | yes | Resolved ticker from CUSIP→ticker mapping via `cusip_security_catalog`. Null when (a) the security has no ticker (debt instruments, private placements), (b) the CUSIP is unmapped (~3% of rows in steady state), or (c) the issuer was delisted before our enrichment ran. Multi-class issuers preserve the actual filed class (e.g. `BRK-A` vs `BRK-B`). |
| holdings[].issuer_name | string | no | Issuer name AS FILED on the 13F (typically all-caps in EDGAR convention, e.g. `APPLE INC`). NOT enriched from Sharadar — for the canonical name use the `cusip_security_catalog` lookup. Multi-class issuers may surface different name variants depending on which share class the filer reported. |
| holdings[].shares | number | no | Share count as reported on the 13F. NOT split-adjusted server-side (preserves the as-filed view) — for split-adjusted aggregations use `/api/v1/tickers/{ticker}/fund-trends`. For securities reported as principal value (debt) the value semantics differ; check the `holdings_quality` side-table flag for outliers. |
| holdings[].value_usd | number | no | Total position USD value AS FILED. Pre-Q3 2022 SEC instruction was 'value reported in thousands'; post-Q3 2022 instruction is 'value reported in actual dollars' — FinRadar's parser auto-detects and normalizes via the `holdings_quality` side-table. The `valueCorrected` / `correctionMethod` / `originalValueTotal` metadata fields surface when correction was applied (see Plan 51 holdings-quality layer for full doc). |
| holdings[].putCall | string | yes | Derivative position type: `"Put"`, `"Call"`, or null for common stock. Options positions are a small minority of 13F filings (most managers report only equity); when present, treat them as a separate signal class — option holdings can dwarf the common-stock book in notional value. |
| holdings[].changeShares | number | yes | Quarter-over-quarter share-count delta (`current_shares - prior_shares`) — present ONLY when `includeChanges=true`. Positive means the fund added shares; negative means it sold. Null when no prior-quarter row exists (i.e. the position is `New`). |
| holdings[].changePercent | number | yes | Quarter-over-quarter percentage change in share count, computed as `(current - prior) / prior` (NOT value-based). Present ONLY when `includeChanges=true`. Null for `New` positions (no prior baseline). For `Closed` positions (in previous quarter, gone this quarter) value is `-1.0`. |
| holdings[].status | string | yes | Position-status label — one of `New` (no prior position), `Increased`, `Decreased`, `Unchanged` (share count exact match), `Closed` (prior position fully sold; appears in `closedPositions` array, NOT in `holdings`). Present ONLY when `includeChanges=true`. The most signal-rich status for momentum analysis is `New` (initial conviction). |
| closedPositions | array | yes | Positions that existed in the prior quarter's filing but are absent from this quarter's — i.e. fully-exited positions. Present ONLY when `includeChanges=true`. Same row shape as `holdings[]`; `status='Closed'` and `changeShares = -prior_shares`. Critical for tracking fund exits — fund flows often surface here as 'big position closed' before the price impact is observable. |
| previousPeriod | string | yes | ISO `YYYY-MM-DD` end-date of the comparison quarter used for QoQ deltas. Present ONLY when `includeChanges=true`. Typically `period - 3 months`, but funds with skipped quarters compare against the most recent prior filing (NOT a stale baseline). |
Sample response
·
- "cik": "0001067983"
- "period": "2025-12-31"
- "holdings":
- "previousPeriod": "2025-09-30"
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 -X POST "https://api.finradar.ai/api/v1/form-13f/holdings?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).