# Get fund holdings See the positions in a disclosed ETF or mutual fund portfolio, with weights, quantities and reported values where available. ## How it works {#how-it-works} - **Choose the portfolio.** Use a fund identifier. Share classes can resolve to a shared portfolio. The response identifies the portfolio whose positions were disclosed. Use `get_profile` for identity and `get_listings` for trading venues. - **Choose the snapshot.** `as_of` selects the latest eligible portfolio date on or before the cutoff. `known_by` uses the filing date when available and the date the disclosure version was first recorded otherwise. Publication dates are blank when unavailable. Omit both filters for the latest available snapshot. - **Read weights as percentages.** A weight of `7.5` means 7.5% of the portfolio. Weights are reported or calculated from position values and net assets where available. Quantities use the accompanying unit when known. Net assets and position values carry their own currencies. Positions can have negative weights, and a security can appear on multiple rows. Synthetic ETFs may disclose an investment basket that differs from their benchmark exposure. - **Page through positions.** Position rows are ordered by descending weight, with unknown weights last. Pass `next_cursor` as `cursor` with the same filters until it is null. If a new disclosure or correction changes the snapshot, start again from the first page. - **Trace a snapshot.** Request `include_sources=true` for available filing, regulator, or fund manager links. The source link may refer to an archive or a newer version. Use the response's `as_of` for the date of the holdings returned here. - **Check coverage.** Coverage varies by fund, market and date. Some disclosures cover only the main investments. Canadian iShares fund-of-funds snapshots show the positions held directly by the fund. Canadian mutual fund portfolios use fund-level LEIs and the main investment schedule from annual or interim issuer financial statements. A null `fund` means no unique portfolio matched the request. ## Request {#request} `GET /api/v1/fund-holdings` with your API key. AI assistants call it as the `get_fund_holdings` tool, with the same parameters. ``` curl "https://financialdb.ai/api/v1/fund-holdings?q=AAPL:US" \ -H "Authorization: Bearer $FDB_API_KEY" ``` ## Parameters {#parameters} | Parameter | Type | Description | |---|---|---| | `include_sources` | boolean | Include available source documents and supporting evidence. Omit for data only. Default: `false`. | | `q` (required) | string | Fund identifier. | | `as_of` | date | Latest eligible portfolio date, inclusive. | | `known_by` | date | Latest eligible filing date or first recorded date, inclusive. | | `limit` | integer: 1–100 | Maximum number of positions. Default: `20`. | | `cursor` | string | Continuation from next_cursor. Omit for the first page. | ## Response {#response} JSON with these fields. A field the source doesn't report is null or left out. | Field | Description | |---|---| | `query` | Requested identifier | | `next_cursor` | Snapshot continuation cursor, or null on the last page | | `fund.name` | Reported fund or portfolio name | | `fund.identifier.type` | Type of portfolio identifier | | `fund.identifier.value` | Identifier of the reported portfolio | | `fund.as_of` | Portfolio date, when known | | `fund.publication_date` | Disclosure publication date, when known | | `fund.total_holdings` | Total number of position rows in the snapshot | | `fund.net_assets.amount` | Reported portfolio net assets in currency units | | `fund.net_assets.currency` | Currency of net assets, when known | | `fund.has_withheld_positions` | Whether the Brazilian disclosure includes confidential aggregate positions | | `fund.source_notice.source` | Data provider | | `fund.source_notice.notice` | Required attribution and reuse notice | | `fund.source_notice.source_url` | Public source catalogue | | `fund.source_notice.terms_url` | Reuse terms | | `fund.sources[].kind` | Source type | | `fund.sources[].url` | Link to the disclosure or source archive | | `holdings[].name` | Reported position name | | `holdings[].security_title` | Reported security title | | `holdings[].isin` | Reported or exchange-verified ISIN | | `holdings[].cusip` | Reported CUSIP | | `holdings[].isin_source.url` | Exchange or issuer reference used to verify an ISIN absent from the holdings file | | `holdings[].isin_source.published` | Reference publication date, when known | | `holdings[].isin_source.sha256` | Fingerprint of the reference version | | `holdings[].asset_class` | Asset class of the position, with other for uncategorized positions | | `holdings[].weight_percent` | Portfolio weight in percent | | `holdings[].quantity` | Reported position quantity | | `holdings[].quantity_unit` | shares, units, principal_amount, contracts or null | | `holdings[].instrument_currency` | Reported currency of the instrument, when known | | `holdings[].market_value.amount` | Reported position value, when its denomination is established | | `holdings[].market_value.currency` | Currency in which the position value is denominated | | `match` | Identifier lookup outcome. A found match can still have an empty page. | ## Errors {#errors} | Status | Meaning | |---|---| | 400 | Missing, unknown or invalid parameter, or an identifier that can't be looked up | | 401 | Missing, unknown or revoked API key | | 402 | No active plan or trial, or the included request allowance is used | | 403 | API access of the account is suspended | | 404 | The identifier matches nothing or is ambiguous. The match field identifies the outcome | | 429 | Over the plan's rate limit; Retry-After says when to retry | | 500 | Internal error; the same request is unlikely to succeed on retry | | 503 | The data couldn't be loaded right now; Retry-After says when to retry, when known | Errors are JSON with an `error` message saying what to fix. Errors are free. See [Errors and limits](https://financialdb.ai/documentation/api/errors-and-limits.md).