ETF Holdings

Available as MCP tool: etf_holdings — call directly from Claude / Cursor / any MCP client. See MCP Server for the 60-second setup.

Live 1 credit (0 if unsupported)

What it does for your agent

etf_holdings returns the latest or as-of regulatory disclosure holdings for a single US-listed ETF — full position list (subject to limit), each row normalized to a common EtfHolding shape with ticker / cusip / isin / sedol identifiers, weight, market_value, shares, and sector / country / asset_type. Rows are sorted by weight descending. Use it when the agent needs the actual position table — to compute concentration (Top-10 weight, HHI), overlap between two ETFs (call twice and diff by CUSIP / ISIN), or to build a thematic basket from an ETF’s underlying. For ETF basic info, top-N summary, and exposure breakdowns, prefer the lighter etf_lookup which is free. This endpoint has one documented exception to the platform’s “the action runs, you pay” billing rule: an unsupported ticker is treated as a free coverage check, not a holdings retrieval. Covered tickers return rows and cost 1 credit; tickers outside coverage return 200 OK with coverage_status="unsupported", empty holdings, and 0 credits. This is a specific sanctioned carve-out for ETF Holdings — it is not a general “no data = free” rule elsewhere on the platform. Pass as_of=YYYY-MM-DD for the latest snapshot with as_of_date <= as_of; cross-ETF overlap is still computed client-side.

Response

EtfHoldingsResult

required

Show EtfHoldingsResult fields

string

required

ETF ticker (uppercased).

string

Fund display name. null when coverage_status="unsupported".

string

Issuer / sponsor.

EtfHolding[]

required

Position rows sorted by weight descending. Empty array when coverage_status="unsupported".

Show EtfHolding fields

string

required

Holding name as filed.

string

Underlying ticker. Often null for bonds, cash, derivatives, and crypto trusts — use cusip / isin to identify these rows.

string

CUSIP. Preferred join key for overlap computation.

string

ISIN. Secondary join key.

string

SEDOL, when present in the filing.

string

equity / fixed_income / cash / derivative / crypto / other.

string

Sector classification; may be null.

string

Country of risk; may be null.

number

Number of shares / units held.

number

Market value in USD.

number

Portfolio weight as a decimal (e.g. 0.071 for 7.1%).

number

Notional for derivatives and special instruments; may be null.

string

required

Per-row identifier of the originating SEC disclosure dataset.

string

Link to the related SEC disclosure dataset, for citation.

string

Regulatory disclosure report date this row reflects.

string

required

Top-level identifier of the originating SEC disclosure dataset.

string

Top-level link to the related SEC disclosure dataset, for citation.

string

Regulatory disclosure snapshot date (YYYY-MM-DD). If as_of is passed, this is the latest available date <= as_of.

string

ISO timestamp when LLMQuant Data last refreshed this holdings data.

boolean

required

true when the snapshot is past the freshness window or a refresh degraded.

string

required

One of full / partial / stale / unsupported.

string

required

Plain-English explanation of what’s covered or why it isn’t.

number

1 for full / partial / stale returns. 0 when coverage_status="unsupported".

number

Account credits remaining.

200 OK · etf_holdings (supported)

{
  "data": {
    "ticker": "SPY",
    "fund_name": "SPDR S&P 500 ETF Trust",
    "issuer": "State Street",
    "holdings": [
      {
        "holding_name": "APPLE INC",
        "ticker": "AAPL",
        "cusip": "037833100",
        "isin": "US0378331005",
        "sedol": null,
        "asset_type": "equity",
        "sector": "Information Technology",
        "country": "US",
        "shares": 168000000,
        "market_value": 30450000000,
        "weight": 0.071,
        "notional_value": null,
        "source": "sec_nport",
        "source_url": "https://www.sec.gov/dera/data/form-n-port-data-sets",
        "as_of_date": "2019-09-30"
      },
      {
        "holding_name": "MICROSOFT CORP",
        "ticker": "MSFT",
        "cusip": "594918104",
        "isin": "US5949181045",
        "sedol": null,
        "asset_type": "equity",
        "sector": "Information Technology",
        "country": "US",
        "shares": 78000000,
        "market_value": 27890000000,
        "weight": 0.065,
        "notional_value": null,
        "source": "sec_nport",
        "source_url": "https://www.sec.gov/dera/data/form-n-port-data-sets",
        "as_of_date": "2019-09-30"
      }
    ],
    "source": "sec_nport",
    "source_url": "https://www.sec.gov/dera/data/form-n-port-data-sets",
    "as_of_date": "2019-09-30",
    "fetched_at": "2026-05-12T03:14:00Z",
    "stale": false,
    "coverage_status": "full",
    "coverage_notice": "Latest available SEC regulatory disclosure snapshot. Not the issuer's daily latest holdings."
  },
  "meta": { "creditsUsed": 1, "remainingCredits": 99 }
}

200 OK · etf_holdings (unsupported)

{
  "data": {
    "ticker": "IBIT",
    "fund_name": null,
    "issuer": null,
    "holdings": [],
    "source": "sec_nport",
    "source_url": null,
    "as_of_date": null,
    "fetched_at": null,
    "stale": false,
    "coverage_status": "unsupported",
    "coverage_notice": "IBIT is not in the current covered ETF list. As a spot Bitcoin trust, its SEC disclosure path differs from the conventional ETFs we cover today."
  },
  "meta": { "creditsUsed": 0, "remainingCredits": 100 }
}

Credit rule

Coverage outcome	HTTP	`creditsUsed`
`full` / `partial` / `stale` (holdings returned)	`200`	`1`
`unsupported` (no holdings, explicit notice)	`200`	`0`
Caller has insufficient credits and ticker is in coverage	`402`	n/a — holdings not returned
Caller has insufficient credits and ticker is outside coverage	`200`	`0` — coverage envelope is delivered without spending credits

Core rule: checking whether a ticker is covered is free; only a resolved holdings retrieval charges 1 credit. This free-when-unsupported behaviour is a documented, sanctioned exception scoped to ETF Holdings — every other endpoint charges as soon as the action runs, even when the result is empty.

Notes

For overlap between two ETFs, call etf_holdings twice and diff client-side. Join by cusip first, then isin, then ticker — holding rows often have a null ticker for bonds / cash / derivatives, but stable identifiers like CUSIP survive.

Concentration metrics (Top-10 weight, HHI) are cheap once you have the rows. Sort is already weight-descending; just slice.

Use etf_lookup first (free) to confirm coverage and read holdings_count before deciding the limit for this call. Broad-market ETFs like VTI have thousands of positions; default limit=50 is enough for most agent workflows.

Current limitations

Not current / daily holdings. Rows reflect the latest SEC official regulatory disclosure snapshot (typically monthly or quarterly disclosure with a public-release lag), not the issuer’s daily book. as_of_date makes this explicit.

Per-row ticker is nullable. Bonds, cash, derivatives, and crypto trusts frequently have no ticker in a holdings row. Always fall back to CUSIP / ISIN for identification and joins.

No etf_compare_holdings server-side. Cross-ETF overlap, weight-difference, and basket comparisons are agent-side computations from two etf_holdings calls.

Only single-date historical lookup is supported. as_of selects the latest snapshot at or before one date; ranges, quarters, and multi-period returns are not part of this endpoint.

Coverage is limited. Currently covered: SPY, QQQ, VTI, SOXX, ARKK and other curated popular ETFs. IBIT / DRAM are outside coverage today.

Regulatory disclosures only. Issuer fact-sheet PDFs and other non-regulatory datasets are not used in this response.

Direct invocation

HTTP / SDK examples

// Default — top 50 by weight
{
  "method": "tools/call",
  "params": {
    "name": "etf_holdings",
    "arguments": { "ticker": "SPY" }
  }
}

// Custom limit + as-of snapshot
{
  "method": "tools/call",
  "params": {
    "name": "etf_holdings",
    "arguments": { "ticker": "VTI", "limit": 200, "as_of": "2025-10-01" }
  }
}

import os, requests

headers = {"Authorization": f"Bearer {os.environ['LLMQUANT_API_KEY']}"}

resp = requests.get(
    "https://api.llmquantdata.com/api/etf/holdings",
    headers=headers,
    params={"ticker": "VTI", "limit": 50, "as_of": "2025-10-01"},
).json()
d = resp["data"]
if d["coverage_status"] == "unsupported":
    print(f"Not covered: {d['coverage_notice']}")
else:
    top10_weight = sum(h["weight"] or 0 for h in d["holdings"][:10])
    print(f"{d['ticker']} snapshot {d['as_of_date']}  Top-10 weight: {top10_weight:.1%}")

curl "https://api.llmquantdata.com/api/etf/holdings?ticker=VTI&limit=50&as_of=2025-10-01" \
  -H "Authorization: Bearer $LLMQUANT_API_KEY"

Full parameter reference

etf_holdings — request parameters

string

required

US-listed ETF ticker (e.g. SPY, QQQ, VTI, SOXX, ARKK). Case-insensitive; the server uppercases and trims. Tickers outside coverage return 200 OK with coverage_status="unsupported" and creditsUsed=0.

integer

default:50

Maximum number of holdings rows to return, sorted by weight descending. Default 50. Max 500. For broad-market ETFs (e.g. VTI), the full underlying list will exceed the maximum; cursor-based pagination is on the roadmap.

string

Optional period date in YYYY-MM-DD format. Returns the latest holdings snapshot with as_of_date <= as_of; omit it for the latest available snapshot.

ETF Lookup

Fund identity, SEC mapping, top holdings summary, and exposure breakdowns — free.

Equity Historical Prices

ETF OHLCV history lives on the equity daily-bar endpoint.

MCP Server setup

Connect Claude / Cursor / any harness in 60 seconds.

Getting Started

Connect

Personal Context

Knowledge Data

Crypto Prices

Prediction Markets

Equity Prices

ETF

Macro Indicators

SEC Filings

News

SEC Form 13F

What it does for your agent

Response

Credit rule

Notes

Current limitations

Direct invocation

Full parameter reference

ETF Lookup

Equity Historical Prices

MCP Server setup

​What it does for your agent

​Response

​Credit rule

​Notes

​Current limitations

​Direct invocation

​Full parameter reference

​Related

ETF Lookup

Equity Historical Prices

MCP Server setup

What it does for your agent

Response

Credit rule

Notes

Current limitations

Direct invocation

Full parameter reference

Related