Historical ETF Holdings Endpoints: Composition Snapshots by Reporting Date

ETF holdings data describes the composition of a fund on a specific date — which securities it held, in what quantities, and at what portfolio weights. Unlike a current snapshot, historical records make it possible to track compositional shifts over time, compare fund states across periods, or reconstruct dated portfolio positions for quantitative and AI-driven workflows. The FinImpulse API now provides programmatic access to this data across available reporting dates.

Two-Endpoint Workflow

Retrieving historical holdings data follows a two-step sequence. The first request establishes which dates are available for the selected ETF; the second retrieves the actual composition for a chosen date.

Step 1: Retrieve Available Reporting Dates

The v1/holdings/history/dates/{symbol} endpoint returns the list of dates for which holdings data is available for the requested ETF. The symbol is passed as a path parameter; an optional start_date parameter filters results to dates on or after a specified value.

{
  "start_date": "2026-05-17",
  "limit": 3,
  "offset": 0
}

The response returns a paginated list of available reporting dates:

"result": {
        "total_count": 7,
        "items_count": 3,
        "items": [
            {
                "type": "date",
                "history_date": "2026-05-18"
            },
            {
                "type": "date",
                "history_date": "2026-05-19"
            },
            {
                "type": "date",
                "history_date": "2026-05-21"
            }
        ]
    }

Step 2: Retrieve the Holdings Snapshot

Once a valid reporting date is confirmed, the v1/holdings/history endpoint returns the full portfolio composition for that date.

Attempting to query holdings without a valid reporting date — one that exists in the dataset for that symbol — will return an empty result.

The request requires two parameters: symbol and date.

{
  "symbol": "SPY",
  "date": "2026-04-26"
}

The response returns a paginated array of holding records, each representing a single position in the fund’s composition on the requested date:

"result": {
        "total_count": 502,
        "items_count": 10,
        "items": [
            {
                "asset": "AAPL",
                "name": "APPLE INC",
                "isin": "US0378331005",
                "cusip": "037833100",
                "shares": 174355685,
                "weight_pct": 6.576,
                "market_value": 47676787718,
                "updated_at": "2026-04-26T02:04:23Z"
            },
            {
                "asset": "ABNB",
                "name": "AIRBNB INC CLASS A",
                "isin": "US0090661010",
                "cusip": "009066101",
                "shares": 5019960,
                "weight_pct": 0.098,
                "market_value": 712219924,
                "updated_at": "2026-04-26T02:04:23Z"
            },
            ...
        ]
  }

The full parameter reference for both endpoints is available in the FinImpulse API documentation.

Coverage and Availability

Historical holdings data is currently available for approximately 8,000 ETF symbols. Coverage begins on January 1, 2026, for most symbols; a subset of around 500 ETFs has records dating back to 2023–2025.

The full list of covered symbols with individual start and end dates is available for download here.

Use Cases for Historical ETF Holdings Data

Historical ETF holdings data is directly applicable across a range of analytical, quantitative, and engineering workflows.

Composition Tracking Over Time

The most direct application of these endpoints is tracking how an ETF’s holdings have changed across reporting dates. By querying the same symbol across multiple dates — retrieved via the dates endpoint — it is possible to build a time-series view of composition shifts: which positions were added, removed, or reweighted between periods. This is relevant for any workflow that treats ETF composition as a dynamic variable rather than a static snapshot.

Holdings Overlap Detection

When comparing two or more ETFs, holdings data from a specific date provides the input needed to calculate the degree of overlap — the proportion of shared positions by weight or count. This is relevant in fund comparison workflows where concentration risk across correlated funds is a concern.

Historical State Reconstruction for Quantitative Models

Many quantitative workflows require knowledge of what a fund held at a specific past date rather than what it holds now. Backtesting a model that involves ETF replication, for example, depends on accurate historical composition data rather than the current holdings applied retroactively. These endpoints provide the dated snapshots needed to reconstruct portfolio state at a given point in time without approximation.

ETF Analysis and Comparison Tools

For developers and teams building ETF detail pages, fund comparison views, or portfolio analysis tools, these endpoints provide the data layer for holdings breakdowns, position weight visualizations, and composition-based filtering.

The holdings endpoint supports filtering and sorting server-side — by weight threshold, position size, or other available fields — reducing the volume of data transferred and the processing required on the client side.

AI-Driven Research Workflows

Holdings snapshots can be a structured input for AI agents and language model pipelines that operate on financial data. An agent evaluating fund behavior at a specific date, generating a summary of top positions, or comparing two funds’ compositions can use these endpoints to retrieve accurate point-in-time data rather than relying on approximations.

Across these workflows, the two endpoints now provide the data layer for any workflow that requires ETF composition at a specific point in time — from overlap detection and backtesting to AI-driven research pipelines.