/api/v1/form-13f/aggregation/basket-holdingsAggregate a basket of fund CIKs into one per-CUSIP consensus view for a quarter.
Aggregate a basket of fund CIKs into one per-CUSIP consensus view for a quarter.
Why use this
Common use case
Replaces the legacy 'pull every holding of every fund into the client, then aggregate' basket flow (which could move 300K+ rows / multiple MB for mega-fund baskets) with ONE indexed server-side aggregation. For each requested CIK it selects the single latest-filed 13F-HR/A for period, applies the same holdings selection as GET /api/v1/form-13f/fund/{cik} (long-equity only, options excluded, transition-CUSIP dedup), then GROUPs BY CUSIP across the basket — so a basket's per-position and total values equal the SUM of the individual /fund reports.
funds_holding is COUNT(DISTINCT cik) — the consensus signal (how many of the basket's managers hold a name). Funds with no 13F for the period appear in basket.pending (not silently dropped). Pass compare_period for quarter-over-quarter change classification (New / Increased / Decreased / Unchanged / Closed) plus value/share deltas, keyed on canonical CUSIP so a corporate-action CUSIP change is not a phantom New/Closed. Max 20 CIKs per request. All monetary amounts USD (post-Plan-51 thousands-vs-actual normalization); share counts as-filed (not split-adjusted). Always-live — no caching.
Parameters
| Name | In | Required | Default | Allowed | Description | Example |
|---|---|---|---|---|---|---|
| ciks | query | required | — | — | Comma-separated CIKs, 1-20. Zero-padded or bare both accepted. | 0001067983,0001649339,0001336528 |
| period | query | required | — | — | Quarter-end YYYY-MM-DD. Holdings come from each fund's latest 13F-HR/A filed for this period. | 2026-03-31 |
| compare_period | query | optional | — | — | Prior quarter-end YYYY-MM-DD. When set, each position gains change_type + prev/delta fields, and Closed positions are synthesized. | 2025-12-31 |
| sort_by | query | optional | value | — | value | shares | funds_holding | pct | name | ticker. | — |
| sort_order | query | optional | desc | — | asc | desc. | — |
| size | query | optional | all | — | Positions per page; default returns all positions (client paginates). Aliases: limit / from / offset. | 50 |
Response schema
| Field | Type | Nullable | Description |
|---|---|---|---|
| period | string | no | ISO YYYY-MM-DD quarter-end echoed from the request. |
| compare_period | string | yes | Prior quarter used for change classification, or null when not requested. |
| generated_at | string | no | UTC timestamp the aggregation was computed (drives an 'as of' label; always-live, never cached). |
| basket | object | no | { total_funds, funds_filed, funds_pending, filed:[{cik,company_name}], pending:[{cik}] } — which requested funds actually filed for this period. |
| totals | object | no | { total_value_usd, total_positions } — basket-wide long-equity value (post-Plan-51 normalization) and count of unique CUSIPs. |
| positions | array | no | One row per CUSIP: { cusip, ticker, name_of_issuer, funds_holding (COUNT DISTINCT funds), value_usd, shares, pct_of_basket }. With compare_period: also change_type, prev_value_usd, value_change_pct, share_change. Long-equity only (options excluded), matching the per-fund /fund report. |
Sample response
- "period": "2026-03-31"
- "compare_period": "2025-12-31"
- "generated_at": "2026-06-28T16:03:07Z"
- "basket":
- "total_funds": 5
- "funds_filed": 5
- "funds_pending": 0
- "filed":
- "pending": []
- "totals":
- "total_value_usd": 412600000000
- "total_positions": 142
- "positions":
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/form-13f/aggregation/basket-holdings" \
-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).