> ## Documentation Index
> Fetch the complete documentation index at: https://docs.focusalpha.ai/llms.txt
> Use this file to discover all available pages before exploring further.
# ETF Holdings
> Security-level ETF portfolio holdings as reported by issuers, with weights, quantities, market values, identifiers and as-of dates.
ETF Holdings provides security-level portfolio holdings reported by ETF issuers. Each observation is associated with an ETF portfolio, an as-of date, and the issuer file it was read from. Historical holdings are available through the FocusAlpha API and MCP.
**Plan:** Fund · **Credits:** 1 per call
Each row is one line of a fund's portfolio on one day: a security, the quantity held, its market value, its weight in the portfolio, and the identifiers the fund printed for it.
## What You Can Use ETF Holdings For
Look through a fund to the companies it actually owns, rather than relying on its stated objective. Measure how concentrated a fund is, and how that concentration changed over time. Find every ETF holding a given company by joining `company_id` back to the company registry. Rebuild sector, country or credit-quality exposure from the underlying lines instead of from a label. Track a fund's turnover by differencing consecutive portfolio dates.
## ETF Holdings Coverage
Holdings are collected from the files ETF issuers publish themselves, so coverage follows what each sponsor discloses and how often. Most large US sponsors publish daily; some publish monthly, and some publish only summary exposure rather than full lines.
Coverage is reported as a measured number rather than described in prose. Call [ETF screen facets](/etf/screening#etf-screen-facets), which is free, to read the current totals, and read the `coverage` block returned alongside every holdings response for the specific fund you queried.
## Key ETF Holdings Fields
`weight_pct` is the line's weight in the portfolio, as a percentage. `quantity` is the number of shares or units held; `par_value` carries face value for debt lines. `market_value` is the line's value in the fund's reporting currency, and `notional_value` carries economic exposure where the two differ. `price`, `currency` and `fx_rate` describe how the value was struck.
`row_kind` classifies the line as one of `equity`, `bond`, `fund`, `cash`, `fx`, `derivative`, `physical`, `crypto` or `other`. `underlying_exposure`, `derivative_kind` and `counterparty` describe derivative lines further.
`cusip`, `isin`, `sedol`, `figi` and `ticker_as_filed` are the identifiers as the fund printed them on that date. `company_id` is FocusAlpha's link from the line to the company registry, where an identifier matched.
Bond lines additionally carry `maturity`, `coupon_pct`, `duration`, `ytm_pct` and `bond_issuer_type`. Equity lines carry `exchange`, `country` and `sector`.
Identifiers and names are as filed on that date. A holding that later changed its ticker keeps the old ticker on old rows, so join a holdings history by CUSIP or ISIN, never by ticker.
## ETF Holdings Date Convention
Three dates appear on every holdings row, and all three are real rather than alternatives.
`valuation_date` is the portfolio valuation date: the closing-price date the file prices at. This is the date to filter and group on.
`position_date` is the day the quantities are effective. It is either the same day as `valuation_date` or the next trading day, depending on whether the fund publishes before or after creations settle. It is null where the offset could not be confirmed.
`issuer_date` is the date label the issuer printed on the file. It is kept because it is the issuer's own claim, and it does not always equal either of the other two.
One holdings file therefore carries two genuinely different dates — a price date and a quantity date — which is why a single as-of column cannot represent it faithfully.
## ETF Holdings Sources
Holdings come from the issuers' own published holdings files. Nothing on this dataset is vendor-supplied, and no line is imputed: a fund that does not publish full lines has no rows rather than estimated ones.
`company_id` is calculated by FocusAlpha rather than reported by the issuer. A null `company_id` is a legitimate terminal state — options, swap legs, bonds and cash are not companies — and the newest portfolio day can lag one run behind on linking and row classification. The `coverage` block's `classified` value says how much of that day is classified.
## Query ETF Holdings
Use the ETF Holdings endpoint to retrieve security-level holdings for one fund. Pass an `etf_id`, ticker, ISIN or CUSIP as the identifier; the newest portfolio date is returned unless you ask for a specific one.
`etf_id` (`E000011`), a ticker (`SPY`), an ISIN, or a CUSIP. Ticker lookup is exact and unambiguous or nothing: an ambiguous symbol returns no row rather than a guess.
A specific portfolio valuation date, `YYYY-MM-DD`. Defaults to the newest date on file.
Comma-separated list of row kinds to include: `equity`, `bond`, `fund`, `cash`, `fx`, `derivative`, `physical`, `crypto`, `other`. Defaults to all.
Return only lines that resolved to a `company_id`.
Rows per page, between 1 and 1000. Page through with `cursor`.
The response returns the fund's identifiers, the `valuation_date` served, a `data` array of holdings lines, a `next_cursor`, and a `coverage` block reporting how many rows the day holds, the sum of absolute weights, and the classified share.
On funds where `exposure_hidden` is true — leveraged, buffer and option-income funds — `market_value` is margin or option premium, not exposure. Read `notional_value` instead, and never sum `market_value` as "the portfolio": a 3x fund sums to roughly flat.
## Related Datasets
See also [ETF NAV and Shares Outstanding](/etf/nav) for the fund-level daily series, [ETF Classification](/etf/classification) for the labels computed from these holdings, [ETF Screening](/etf/screening) to select funds by measured portfolio characteristics, and [13F Institutional Holdings](/ownership/13f) for holdings reported by investment managers.
```bash cURL theme={null}
curl "https://api.focusalpha.ai/v1/etfs/XBI/holdings?row_kind=equity&limit=1" \
-H "Authorization: Bearer $FOCUSALPHA_API_KEY"
```
```json Response theme={null}
{
"etf_id": "E000074",
"ticker": "XBI",
"portfolio_id": "P000423",
"valuation_date": "2026-08-31",
"data": [
{
"valuation_date": "2026-08-31T00:00:00.000Z",
"position_date": "2026-09-01T00:00:00.000Z",
"issuer_date": "2026-08-31T00:00:00.000Z",
"line_no": 1,
"name": "MODERNA INC",
"ticker_as_filed": "MRNA",
"cusip": "60770K107",
"isin": null,
"sedol": "BGSXTS3",
"figi": null,
"row_kind": "equity",
"underlying_exposure": "equity",
"derivative_kind": null,
"counterparty": null,
"weight_pct": "2.806364",
"quantity": "2281374",
"par_value": null,
"market_value": null,
"notional_value": null,
"price": null,
"currency": "USD",
"fx_rate": null,
"exchange": null,
"country": null,
"sector": null,
"maturity": null,
"coupon_pct": null,
"duration": null,
"ytm_pct": null,
"bond_issuer_type": null,
"company_id": "cmp_005766"
}
],
"next_cursor": "1",
"coverage": {
"n_rows": 157,
"weight_sum": "100.01",
"classified": "1.000",
"note": "Holdings are the pool's: share classes on one pool share them. classified < 1 means the newest lines have not been through row classification yet; company_id can lag a day for the same reason. exposure_hidden funds: market_value on a swap or option line is margin or premium, not the exposure — read notional_value."
}
}
```