--- title: "Returns per-security holdings from SEC Form N-PORT primary documents — one row per investment-or-security line in a mutual fund / ETF / closed-end fund's monthly portfolio report" method: GET path: "/v1/fund-holdings" --- # Returns per-security holdings from SEC Form N-PORT primary documents — one row per investment-or-security line in a mutual fund / ETF / closed-end fund's monthly portfolio report `GET /v1/fund-holdings` ## Request - Base URL: `https://api.keyvex.com` - URL: `https://api.keyvex.com/v1/fund-holdings` - Auth: API key in header `x-api-key` Returns per-security holdings from SEC Form N-PORT primary documents — one row per investment-or-security line in a mutual fund / ETF / closed-end fund's monthly portfolio report. Use this when the user asks about: which funds hold a specific stock or bond, a fund's complete portfolio composition, fund-level derivative exposure (swaps, options, futures), repo positions, concentration by issuer, or to compose 'which ETFs added X this month' / 'which funds shorted Y' style queries. Source: parsed from each NportFiling's primary_doc.xml. asset_cat is SEC's own code, and these twenty are the only ones the data holds — EC common equity; EP preferred equity; DBT debt, Treasuries included; LON loan; ABS-MBS asset-backed, mortgage; ABS-O asset-backed, other; ABS-CBDO asset-backed, CDO/CBO; ABS-APCP asset-backed commercial paper; SN structured note; STIV short-term investment vehicle, money-market and liquidity pools; RA repurchase and reverse-repurchase agreement; RE real estate; COMM commodity; DE equity derivative; DIR interest-rate derivative; DFE foreign-exchange derivative; DCR credit derivative; DCO commodity derivative; DO other derivative; OTHER other. Anything else is refused with this list. Useful filter combos: ticker='NVDA' all funds holding NVDA cusip='037833100' AAPL by CUSIP (more reliable than ticker for N-PORT) is_derivative=true, filer_name='BlackRock' the BlackRock FAMILY's derivative book — a name is a substring, and this one spans five trusts. filer_cik picks one of them. derivative_type='swap' every swap position in the universe asset_cat='RA' repo and reverse-repo exposure payoff_profile='Short' short positions only min_pct_of_portfolio=5 concentrated positions (>=5% of NAV) filer_cik='0000884394' one fund's complete portfolio counterparty='Morgan Stanley' every fund's exposure to one dealer min_notional=10000000 derivatives with >=$10M of EXPOSURE (not fair value — see min_notional) derivative_type='swap', expiration_until='2026-12-31' swaps rolling off before year-end maturity_since='2026-01-01', maturity_until='2026-12-31' bonds maturing this year Each holding ties to its parent NportFiling via filing_id. Read the parent for fund metadata (file_date, file_number, amendment flag); read the holding for security-level detail. is_derivative + derivative_type distinguish structured derivative rows from straight equity/debt holdings. DERIVATIVE + DEBT TERMS are extracted and filterable (2026-08-09). Derivatives carry deriv_notional_amount, deriv_counterparty_name/_lei, deriv_expiration_date, deriv_unrealized_appreciation, and the leg-level detail — put/call, written/purchased, strike, share count and delta for options; swap flag and upfront payment/receipt for swaps; both currency legs for forwards. Debt rows carry debt_maturity_date, coupon kind, annualized rate, default, arrears and paid-in-kind flags. USE min_notional, NOT min_value_usd, TO SIZE A DERIVATIVE. Fair value and exposure differ by orders of magnitude: a real interest-rate swap here shows value_usd -49,184 against a notional of 6,795,000. Ranking derivatives by value_usd understates them by ~100x. BACKFILL IN PROGRESS: these fields are populated on filings re-extracted since 2026-08-09 and are absent (null) on the rest until it completes. A null term on an older filing means not-yet-extracted, NOT absent from the source — do not read it as 'this swap has no counterparty'. The parent filing's primary_document_url always has the authoritative detail. COVERAGE: holdings begin with N-PORT filings FILED 2024-06-01. Most filings from then on have holdings rows, but not all: some are still metadata-only in get_nport_filings (not yet extracted — about 4% as of September 2026). Filings before 2024-06-01 are outside this coverage. For a filing with no holdings here, follow primary_document_url in get_nport_filings. An empty result for a filing means not-extracted, not an empty fund. ## Query parameters - `filing_id` string - `filer_cik` string - `filer_name` string - `period_ending` string - `name` string - `cusip` string - `ticker` string - `isin` string - `asset_cat` 'EC' | 'EP' | 'DBT' | 'LON' | 'ABS-MBS' | 'ABS-O' | 'ABS-CBDO' | 'ABS-APCP' | 'SN' | 'STIV' | 'RA' | 'RE' | 'COMM' | 'DE' | 'DIR' | 'DFE' | 'DCR' | 'DCO' | 'DO' | 'OTHER' - `is_derivative` boolean - `derivative_type` 'future' | 'forward' | 'swap' | 'option' | 'warrant' | 'swaption' | 'other' - `country` string - `payoff_profile` 'Long' | 'Short' - `min_value_usd` number - `min_pct_of_portfolio` number - `min_notional` number - `counterparty` string - `expiration_since` string - `expiration_until` string - `maturity_since` string - `maturity_until` string - `since` string - `until` string - `sort_by` 'value_usd' | 'pct_of_portfolio' | 'period_ending' - `sort_order` 'desc' | 'asc' - `limit` integer ## Response `200` JSON envelope: { results: [...], count, has_more }. ## Other responses - `400`: Invalid parameter. - `401`: Missing or invalid API key. - `402`: This tool requires a higher plan (upgrade_required). Retrying will not help. - `429`: Tier rate/quota limit reached (rate_limited). Retry-After points at the reset. --- [API](https://skmtc.dev/keyvex/apis/keyvex-api.md) · [All operations](https://skmtc.dev/keyvex/apis/keyvex-api/llms.txt) · [OpenAPI document](https://skmtc.dev/keyvex/apis/keyvex-api/revisions/01c0210c19cd?raw)