/api/v1/form-13f/fund/bulkBulk query multiple funds in one request (basket analysis).
Bulk query multiple funds in one request (basket analysis).
Why use this
Common use case
Batches up to 20 fund-detail lookups into a single request — replaces 20 sequential calls to GET /api/v1/form-13f/fund/{cik} with one round-trip. Designed for 'basket' workflows: build a watchlist of hedge funds (e.g. Tiger Global + Citadel + Renaissance + Bridgewater), then poll this endpoint for an aggregated view of their Q4 2025 books.
Two detail levels: summary (default — top-10 holdings + portfolio totals per fund, ~50KB response for 20 funds) or full (complete holdings per fund, paginated via size/from; can be 10-50MB for index-fund-heavy baskets like Vanguard + BlackRock). Use summary for dashboard overview tiles; full only when you need every position.
CIKs that exist but have no filing for the requested period return with status: 'no_filing' (NOT silently dropped) — frontends can surface coverage gaps. The meta.{ok_count, no_filing_count, unknown_cik_count} aggregate counts make it trivial to render 'Basket: 15 of 20 funds reporting for Q4 2025'. All monetary amounts are in USD (post-Plan-51 thousands correction); share counts are NOT split-adjusted (as-filed view) — for split-adjusted aggregations use GET /api/v1/tickers/{ticker}/fund-trends.
Parameters
| Name | In | Required | Default | Allowed | Description | Example |
|---|---|---|---|---|---|---|
| ciks | body | required | — | — | Array of CIK strings, max 20. e.g. ["1067983", "1649339"] | 0000320193,0000789019 |
| period | query | optional | — | — | Report period YYYY-MM-DD. Applied to all funds. | 2025Q4 |
| detail | query | optional | summary | — | 'summary' or 'full'. Summary returns top 10 holdings only. | — |
| size | query | optional | 50 | — | Holdings per page (only for detail=full). Accepted alias: `limit`. | 50 |
| from | query | optional | 0 | — | Pagination offset (only for detail=full). Accepted alias: `offset`. | 0 |
Response schema
| Field | Type | Nullable | Description |
|---|---|---|---|
| period | string | no | ISO `YYYY-MM-DD` reporting period applied to all funds in the bulk query (always a calendar quarter end). When omitted from input, defaults to the latest quarter for which ALL requested CIKs have a filing — funds missing a filing for this period appear in the `funds` array with `status: 'no_filing'`. |
| detail | string | no | Echoed back from the request. `summary` (default) returns each fund's top-10 holdings + portfolio totals; `full` returns the complete holdings array per fund (paginated via `size`/`from`). Use `summary` for basket-overview UIs; `full` for deep-dive analysis where you need every position. |
| funds | array | no | Array of per-fund report rows — one entry per requested CIK. Order matches the order of CIKs in the request. Funds without a filing for the requested `period` appear here with `status: 'no_filing'` and `holdings: []` rather than being silently dropped — clients can detect coverage gaps. |
| funds[].cik | string | no | 10-char zero-padded CIK echoed from the request. Use as a stable join key in client-side basket aggregation. Berkshire = `0001067983`, Bridgewater = `0001350694`, Renaissance = `0001037389`. |
| funds[].name | string | no | Registrant name AS FILED on the most recent 13F-HR (typically all-caps in EDGAR convention). NOT alias-normalized — for the user-friendly alias (e.g. 'Warren Buffett') consult the `filer_aliases` admin table via [GET /api/v1/form-13f/filers](/docs/institutional-holdings/form-13f-api/get-form-13f-filers). |
| funds[].status | string | no | Per-fund result status: `ok` (filing found and parsed), `no_filing` (CIK exists but no 13F for this period), `unknown_cik` (CIK not in our 13F filer universe). Frontends should branch on this before reading `holdings`. |
| funds[].portfolio_value_usd | number | yes | Total portfolio USD value (sum of `holdings[].value_usd`, post-Plan-51 thousands-vs-actual normalization). Null when `status != 'ok'`. Berkshire Q4 2025 ≈ $310B; mid-tier hedge funds $1-10B; family offices $50M-1B. |
| funds[].holdings_count | integer | yes | Number of position rows in this fund's filing for the requested period. Null when `status != 'ok'`. Berkshire-shaped books: ~50; mid-tier hedge funds: 50-500; index-fund books (Vanguard, BlackRock): 3000-9000+. |
| funds[].holdings | array | yes | Position rows — top 10 by `value_usd` when `detail=summary`, OR paginated full list when `detail=full`. Each row carries the same shape as `GET /api/v1/form-13f/fund/{cik}` holdings: `{ cusip, ticker, name_of_issuer, shares, value_usd, put_call, ... }`. Null when `status != 'ok'`. |
| funds[].error | string | yes | Per-fund error message — populated only when `status` is `no_filing` or `unknown_cik`. Examples: `'No 13F-HR filing for period 2025-09-30'`, `'CIK 0009999999 not found in 13F filer universe'`. Use to surface gaps in basket coverage. |
| meta | object | no | Bulk-query metadata: `{ requested_count, ok_count, no_filing_count, unknown_cik_count, detail }`. Useful for surfacing coverage stats: 'Basket: 15 of 20 funds reporting for Q4 2025'. |
Sample response
- "period": "2025-09-30"
- "detail": "summary"
- "funds":
- "meta":
- "requested_count": 2
- "ok_count": 2
- "no_filing_count": 0
- "unknown_cik_count": 0
- "detail": "summary"
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/fund/bulk" \
-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).