All Holdings List

Returns the full holdings composition for a selected ETF on a specific historical reporting date.

Thе all holdings list is the primary endpoint in the historical holdings workflow. 

Before calling this endpoint, use v1/holdings/history/dates/{symbol} to retrieve the list of available reporting dates for the selected ETF, then pass a valid date here to retrieve the complete portfolio composition as recorded on that date. 

Note that historical holdings coverage begins on January 1, 2026, for most ETFs (~8,000 symbols). A subset of ~500 ETFs includes records dating back to 2023-2025. The full list of covered symbols with individual start and end dates is available for download here.

Asset Type Compatibility

This endpoint is applicable only to ETFs. Stocks and mutual funds are not supported.

If no holdings data is available for the requested symbol and date combination, the response returns an empty items array.

When to Use This Endpoint

  • Retrieve the full portfolio composition of an ETF on a specific date.
  • Display a holdings breakdown table in an ETF detail or comparison view.
  • Analyze position weights and market values for a specific reporting date.
  • Screen or filter holdings by weight threshold, market value, or other available fields.
  • Track changes in ETF composition across reporting dates.
  • Feed portfolio analysis, overlap detection, or AI-driven workflows that operate on full holdings snapshots.

Request Parameters

POST
v1/holdings/history
symbol stringrequired

Asset identifier (ticker symbol).

date stringrequired

Holdings reporting date (YYYY-MM-DD). Must be a date available for the requested symbol.

Use v1/holdings/history/dates/{symbol} to retrieve the list of available dates.

filters arrayoptional

Optional filter expressions.

Each filter condition is defined as: [field, operator, value]. Conditions can be combined using logical operators and/or.

Supported operators:

Numeric fields:

  • > - greater than
  • >= - greater than or equal
  • < - less than
  • <= - less than or equal
  • = - equals
  • <> - not equal

String fields:

  • like – pattern match (requires % as a wildcard)
  • not_like - pattern does not match (requires % as a wildcard)
  • contains - value exists in string
  • not_contains - value does not exist in string
  • startswith - string starts with value
  • endswith - string ends with value

% usage examples:

  • %abc% - matches any string containing "abc"
  • abc% - matches any string starting with "abc"
  • %abc - matches any string ending with "abc"

Example:

"filters": [
  "weight_pct", ">", 1
],
sort_by arrayoptional

Optional sorting configuration for result items. Each sorting setup is defined as [selector, desc]:

  • selector - Metric used for sorting (e.g., weight_pct).
  • desc - Sorting direction (true for descending, false for ascending).

Sortings can be combined using ,.

Example:

"sort_by": [
    {
        "selector": "weight_pct",
        "desc": true
    }
]
offset integeroptional

Pagination offset (0-based).

limit integeroptional

Maximum number of records returned (user-defined).

tag stringoptional

User-defined identifier for the task (max 255 characters).

It is returned in the response data object, allowing you to match results with the corresponding request. It does not affect API processing or filtering logic.

Example Request
curl --location "https://api.finimpulse.com/v1/holdings/history" \
  --header "Content-Type: application/json" \
  --header "Authorization: Bearer <API_TOKEN>" \
  -d '{
      "symbol": "SPY",
      "date": "2026-04-26",
      "limit": 20,
      "offset": 0,
      "tag": "just tag"
  }'
using System.Net.Http;
using System.Net.Http.Headers;
using System.Text;

var client = new HttpClient();
var url = "https://api.finimpulse.com/v1/holdings/history";

client.DefaultRequestHeaders.Authorization = new AuthenticationHeaderValue("Bearer", "<API_TOKEN>");
client.DefaultRequestHeaders.Accept.Add(new MediaTypeWithQualityHeaderValue("application/json"));

var json = @"{
    ""symbol"": ""SPY"",
    ""date"": ""2026-04-26"",
    ""limit"": 20,
    ""offset"": 0,
    ""tag"": ""just tag""
}";
var content = new StringContent(json, Encoding.UTF8, "application/json");

var response = await client.PostAsync(url, content);
var result = await response.Content.ReadAsStringAsync();
Console.WriteLine(result);
<?php
$curl = curl_init();

curl_setopt_array($curl, [
  CURLOPT_URL => "https://api.finimpulse.com/v1/holdings/history",
  CURLOPT_RETURNTRANSFER => true,
  CURLOPT_CUSTOMREQUEST => "POST",
  CURLOPT_HTTPHEADER => [
    "Content-Type: application/json",
    "Authorization: Bearer <API_TOKEN>"
  ],
  CURLOPT_POSTFIELDS => json_encode(
[
      "symbol" => "SPY",
      "date" => "2026-04-26",
      "limit" => 20,
      "offset" => 0,
      "tag" => "just tag"
    ]
  )
]);

$response = curl_exec($curl);
curl_close($curl);

echo $response;
import urllib.request
import json

url = "https://api.finimpulse.com/v1/holdings/history"
headers = {
    "Content-Type": "application/json",
    "Authorization": "Bearer <API_TOKEN>"
}
data = {
    "symbol": "SPY",
    "date": "2026-04-26",
    "limit": 20,
    "offset": 0,
    "tag": "just tag"
}

req = urllib.request.Request(url,
    data=json.dumps(data).encode("utf-8"),
    headers=headers,
    method="POST")

with urllib.request.urlopen(req) as response:
    result = json.loads(response.read().decode("utf-8"))
    print(result)
const https = require('https');

const data = JSON.stringify({
    "symbol": "SPY",
    "date": "2026-04-26",
    "limit": 20,
    "offset": 0,
    "tag": "just tag"
});

const options = {
  method: 'POST',
  headers: {
    'Content-Type': 'application/json',
    'Authorization': 'Bearer <API_TOKEN>',
    'Content-Length': Buffer.byteLength(data)
  }
};

const req = https.request('https://api.finimpulse.com/v1/holdings/history', options, (res) => {
  let body = '';
  res.on('data', chunk => body += chunk);
  res.on('end', () => console.log(JSON.stringify(JSON.parse(body), null, 2)));
});

req.on('error', (e) => console.error(e));
req.write(data);
req.end();

Response

Pagination Fileds

total_count integer

Total number of holding records matching the request parameters.

items_count integer

Number of records returned in this response.

items array

Array of holding records.

Holding Item

Each item represents a single position in the ETF's holdings composition on the requested date.

asset string

Asset identifier (ticker symbol).

name string

Full name of the security.

isin string

International Securities Identification Number (ISIN).

cusip string

CUSIP identifier.

shares integer

Number of shares held.

weight_pct number

Position weight as a percentage of the total portfolio.

market_value number

Market value of the position in the fund's reporting currency.

updated_at string

Timestamp of when the holdings record became available (ISO 8601).

Example Response
{
    "task_id": "e57cafe2-2ac1-4c67-9360-4a1ea8ad6c8e",
    "status_code": 20000,
    "status_message": "OK",
    "live": true,
    "cost": 0.00045,
    "data": {
        "symbol": "SPY",
        "limit": 20,
        "offset": 0,
        "filters": [
            "weight_pct",
            ">",
            1
        ],
        "tag": "just tag",
        "date": "2026-04-26",
        "sort_by": [
            {
                "selector": "weight_pct",
                "desc": true
            }
        ]
    },
    "result": {
        "total_count": 12,
        "items_count": 12,
        "items": [
            {
                "asset": "NVDA",
                "name": "NVIDIA CORP",
                "isin": "US67066G1040",
                "cusip": "67066G104",
                "shares": 288592151,
                "weight_pct": 7.947,
                "market_value": 57617820649,
                "updated_at": "2026-04-26T02:04:23Z"
            },
            {
                "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": "MSFT",
                "name": "MICROSOFT CORP",
                "isin": "US5949181045",
                "cusip": "594918104",
                "shares": 88187105,
                "weight_pct": 5.057,
                "market_value": 36665876659,
                "updated_at": "2026-04-26T02:04:23Z"
            },
            {
                "asset": "AMZN",
                "name": "AMAZON.COM INC",
                "isin": "US0231351067",
                "cusip": "023135106",
                "shares": 116013043,
                "weight_pct": 4.082,
                "market_value": 29594291883,
                "updated_at": "2026-04-26T02:04:23Z"
            },
            {
                "asset": "AVGO",
                "name": "BROADCOM INC",
                "isin": "US11135F1012",
                "cusip": "11135F101",
                "shares": 56305930,
                "weight_pct": 3.261,
                "market_value": 23646462584,
                "updated_at": "2026-04-26T02:04:23Z"
            },
            {
                "asset": "GOOGL",
                "name": "ALPHABET INC CL A",
                "isin": "US02079K3059",
                "cusip": "02079K305",
                "shares": 69140800,
                "weight_pct": 3.232,
                "market_value": 23432458020,
                "updated_at": "2026-04-26T02:04:23Z"
            },
            {
                "asset": "GOOG",
                "name": "ALPHABET INC CL C",
                "isin": "US02079K1079",
                "cusip": "02079K107",
                "shares": 55550998,
                "weight_pct": 2.588,
                "market_value": 18763418133,
                "updated_at": "2026-04-26T02:04:23Z"
            },
            {
                "asset": "META",
                "name": "META PLATFORMS INC CLASS A",
                "isin": "US30303M1027",
                "cusip": "30303M102",
                "shares": 25980039,
                "weight_pct": 2.362,
                "market_value": 17125718902,
                "updated_at": "2026-04-26T02:04:23Z"
            },
            {
                "asset": "TSLA",
                "name": "TESLA INC",
                "isin": "US88160R1014",
                "cusip": "88160R101",
                "shares": 33407856,
                "weight_pct": 1.722,
                "market_value": 12485893026,
                "updated_at": "2026-04-26T02:04:23Z"
            },
            {
                "asset": "JPM",
                "name": "JPMORGAN CHASE + CO",
                "isin": "US46625H1005",
                "cusip": "46625H100",
                "shares": 32027992,
                "weight_pct": 1.377,
                "market_value": 9983370818,
                "updated_at": "2026-04-26T02:04:23Z"
            },
            {
                "asset": "LLY",
                "name": "ELI LILLY + CO",
                "isin": "US5324571083",
                "cusip": "532457108",
                "shares": 9413312,
                "weight_pct": 1.191,
                "market_value": 8638614751,
                "updated_at": "2026-04-26T02:04:23Z"
            },
            {
                "asset": "XOM",
                "name": "EXXON MOBIL CORP",
                "isin": "US30231G1022",
                "cusip": "30231G102",
                "shares": 49643075,
                "weight_pct": 1.031,
                "market_value": 7473201455,
                "updated_at": "2026-04-26T02:04:23Z"
            }
        ]
    }
}

Notes

  • The date parameter must correspond to an available reporting date for the requested symbol. Use v1/holdings/history/dates/{symbol} to retrieve the list of valid dates.
  • weight_pct values reflect the position weight at the time of reporting and may not sum to exactly 100 due to rounding or the presence of cash and other non-equity positions.