Skip to content
/api/v1/form-13f/holdings

Search 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 a widely-used commercial SEC-data API's 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

NameInRequiredDefaultAllowedDescriptionExample
querybodyrequired——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
frombodyoptional0—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
sizebodyoptional50—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
sortbodyoptional——Sort specification array (the widely-used commercial SEC-data API's 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"}}]
includeChangesbodyoptionalfalse—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

FieldTypeNullableDescription
statusstringno—
request_idstringyes—
timestampstringno—
dataobjectno—
data.totalobjectno—
data.total.valueintegerno—
data.total.relationstringno—
data.dataarrayno—
data.data[].accessionNostringyes—
data.data[].formTypestringyes—
data.data[].filedAtstringyes—
data.data[].cikstringyes—
data.data[].companyNamestringyes—
data.data[].correctionMethodstringyes—
data.data[].periodOfReportstringyes—
data.data[].isAmendmentbooleanyes—
data.data[].valueCorrectedbooleanyes—
data.data[].tableEntryTotalintegeryes—
data.data[].tableValueTotalintegeryes—
data.data[].originalValueTotalintegeryes—
data.data[].holdingsarrayno—
data.data[].holdings[].nameOfIssuerstringyes—
data.data[].holdings[].titleOfClassstringyes—
data.data[].holdings[].cusipstringyes—
data.data[].holdings[].canonicalCusipstringyes—
data.data[].holdings[].tickerstringyes—
data.data[].holdings[].putCallstringyes—
data.data[].holdings[].investmentDiscretionstringyes—
data.data[].holdings[].otherManagerstringyes—
data.data[].holdings[].figistringyes—
data.data[].holdings[].valueintegeryes—
data.data[].holdings[].shrsOrPrnAmtobjectno—
data.data[].holdings[].shrsOrPrnAmt.sshPrnamtnumberyes—
data.data[].holdings[].shrsOrPrnAmt.sshPrnamtTypestringno—
data.data[].holdings[].votingAuthorityobjectno—
data.data[].holdings[].votingAuthority.Solenumberyes—
data.data[].holdings[].votingAuthority.Sharednumberyes—
data.data[].holdings[].votingAuthority.Nonenumberyes—
data.data[].holdings[].changeSharesnumberyesOptional; omitted when not applicable.
data.data[].holdings[].changePercentnumberyesOptional; omitted when not applicable.
data.data[].holdings[].statusstringyesOptional; omitted when not applicable.
data.closedPositionsarraynoOptional; omitted when not applicable.
data.previousPeriodstringyesOptional; omitted when not applicable.

Sample response

·
  • "status": "success"
  • "request_id": null
  • "timestamp": "2026-09-25T12:00:00Z"
  • "data":
    • "total":
    • "data":
    }
}

Errors

StatusLabelDescription
200OKRequest succeeded.
400Bad RequestInvalid query, body, or path parameter.
401UnauthorizedMissing or invalid Authorization header / api_Token.
402Payment RequiredInsufficient token balance for this call. Top up
429Too Many RequestsRate limit exceeded for your tier (see /pricing for tier limits). Tier limits
500Server ErrorUnexpected server-side failure. Retry with backoff; report if persistent.

Code samples

curl -X POST "https://api.finradar.ai/api/v1/form-13f/holdings" \
  -H "X-API-Key: YOUR_API_KEY" \
  -H "Content-Type: application/json" \
  -d '{
  "query": "cik:1067983 AND periodOfReport:2025-12-31",
  "from": "0",
  "size": "50",
  "sort": "[{\"filedAt\": {\"order\": \"desc\"}}]",
  "includeChanges": "true"
}'

Generate an API key in /account/credentials to run live queries (literal YOUR_API_KEY placeholder shown until then).

Try it

Related endpoints

/api/v1/form-13f/filers10 tokens/api/v1/form-13f/cover-pages10 tokens/api/v1/form-13f/filing-progressfree/api/v1/tickers/{ticker}/fund-trends10 tokens