---
title: "ETF Holdings"
method: GET
path: "/gateway/v1/equity/etf/holdings"
tags: ["Equity"]
---

# ETF Holdings

`GET /gateway/v1/equity/etf/holdings`

## Request

- Base URL: `https://api.asksurf.ai`
- URL: `https://api.asksurf.ai/gateway/v1/equity/etf/holdings`
- Auth: HTTP bearer

Returns a stored ETF or index-fund portfolio snapshot plus its immediately previous snapshot, ordered newest to oldest. Available quarterly periods describe the stored holdings history. The latest pair is cached for 6 hours; an explicit historical as_of pair is cached until the next calendar quarter.

## Query parameters

- `symbol` string, required: US-listed ETF or index-fund ticker symbol
- `as_of` string: Select the composition effective on or before this YYYY-MM-DD date; the response also includes its immediately previous snapshot
- `asset_class` 'equity' | 'bond': Filter holdings by instrument type
- `limit` integer: Maximum holdings to return
- `offset` integer: Number of holdings to skip

## Response `200`

OK

- DataObjectResponseEquityETFHoldingsResponse
  - `$schema` string, uri: A URL to the JSON Schema for this object.
  - `data` EquityETFHoldingsResponse, required
    - `available_periods` EquityETFHoldingsPeriod[], nullable, required: Available quarterly portfolio periods, ordered newest to oldest
      - `as_of` string, date, required: Exact date to send as as_of when selecting this period
      - `quarter` integer, required: Calendar quarter number
      - `year` integer, required: Calendar year of the portfolio period
    - `snapshots` EquityETFHoldingsSnapshot[], nullable, required: Selected and immediately previous portfolio snapshots, ordered newest to oldest
      - `fund` EquityETFFund, required
        - `as_of` string, required: Effective portfolio date
        - `asset_class` string, required: Fund asset class
        - `cik` string, required: SEC central index key
        - `filing_date` string, required: SEC filing date
        - `name` string, required: Fund name
        - `offset` integer, required: Requested offset within the filtered holdings result
        - `returned` integer, required: Holdings returned after applying filters and pagination
        - `source` string, required: Provider source type
        - `total_holdings` integer, required: Total holdings in the unfiltered provider snapshot; asset_class filters only the returned holdings
        - `total_net_assets` number, double, nullable, required: Total net assets; null when unavailable
      - `holdings` EquityETFHolding[], nullable, required: Holdings ordered by portfolio weight
        - `asset_class` string, nullable, required: Holding asset class; null when unavailable
        - `cusip` string, nullable, required: CUSIP identifier; null when unavailable
        - `isin` string, nullable, required: ISIN identifier; null when unavailable
        - `logo_url` string, nullable, required: Holding logo image URL; null when no ticker is available
        - `market_value` number, double, nullable, required: Reported market value; null when unavailable
        - `name` string, nullable, required: Holding name; null when unavailable
        - `shares` number, double, nullable, required: Reported share or unit quantity; null when unavailable
        - `ticker` string, nullable, required: Holding ticker; null when the instrument has no ticker
        - `weight` number, double, nullable, required: Portfolio weight in percentage points; null when unavailable
    - `symbol` string, required: ETF or index-fund ticker symbol
  - `meta` ObjectResponseMeta, required
    - `cached` boolean, required: Whether this response was served from cache
    - `credits_used` integer, required: Credits deducted for this request
    - `empty_reason` string: Hint explaining why the data array is empty, when applicable

## Other responses

- `default`: Error

---

[API](https://skmtc.dev/asksurf/apis/asksurf-public-rest-api.md) - [All operations](https://skmtc.dev/asksurf/apis/asksurf-public-rest-api/llms.txt) - [OpenAPI document](https://skmtc.dev/asksurf/apis/asksurf-public-rest-api/revisions/91774fdd5302?raw)