This endpoint provides a high-level snapshot of how a fund is constructed: asset allocation, sector exposure, and aggregated valuation characteristics of the underlying holdings.
Asset Type Compatibility
- Mutual funds: Returns a complete holdings overview when underlying holdings data is available.
- ETFs: Returns a complete holdings overview when underlying holdings data is available.
- Stocks: Returns null values for all holdings fields because the asset does not represent a diversified portfolio. However, the request can still be executed, as all assets share a unified symbol universe.
When to Use This Endpoint
- Retrieve a fund’s high-level allocation mix (cash, equity, bonds, and other instruments).
- Display sector exposure breakdowns for ETFs and mutual funds.
- Populate Holdings Overview/Portfolio Composition sections in asset pages.
- Support fund screening and comparison based on holdings-derived characteristics.
Request Parameters
v1/holdings/general
Asset identifier (ticker symbol).
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.
curl --location "https://api.finimpulse.com/v1/holdings/general" \
--header "Content-Type: application/json" \
--header "Authorization: Bearer <API_TOKEN>" \
-d '{
"symbol": "SPY",
"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/general";
client.DefaultRequestHeaders.Authorization = new AuthenticationHeaderValue("Bearer", "<API_TOKEN>");
client.DefaultRequestHeaders.Accept.Add(new MediaTypeWithQualityHeaderValue("application/json"));
var json = @"{
""symbol"": ""SPY"",
""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/general",
CURLOPT_RETURNTRANSFER => true,
CURLOPT_CUSTOMREQUEST => "POST",
CURLOPT_HTTPHEADER => [
"Content-Type: application/json",
"Authorization: Bearer <API_TOKEN>"
],
CURLOPT_POSTFIELDS => json_encode(
[
"symbol" => "SPY",
"tag" => "just tag"
]
)
]);
$response = curl_exec($curl);
curl_close($curl);
echo $response;
import urllib.request
import json
url = "https://api.finimpulse.com/v1/holdings/general"
headers = {
"Content-Type": "application/json",
"Authorization": "Bearer <API_TOKEN>"
}
data = {
"symbol": "SPY",
"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",
"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/general', 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
The response is a single object containing holdings overview fields for the requested asset.
General Information
Asset identifier (ticker symbol).
Asset Allocation
Percentage of fund assets held in cash.
Percentage of fund assets held in stocks.
Percentage of fund assets held in bonds.
Percentage of fund assets held in other instruments.
Percentage of fund assets held in preferred stock.
Percentage of fund assets held in convertible securities.
Valuation Characteristics (Holdings-weighted)
Price-to-earnings (P/E) ratio.
Holdings-weigted price-to-book (P/B) ratio.
Price-to-sales (P/S) ratio.
Price-to-cash flow (P/CF) ratio.
Market Size and Growth Characteristics
Median market capitalization of fund holdings.
3-year earnings growth.
Sector Allocation
Percentage of fund assets in the real estate sector.
Percentage of fund assets in the consumer cyclical sector.
Percentage of fund assets in the basic materials sector.
Percentage of fund assets in the consumer defensive sector.
Percentage of fund assets in the technology sector.
Percentage of fund assets in the communication services sector.
Percentage of fund assets in the financial services sector.
Percentage of fund assets in the utilities sector.
Percentage of fund assets in the industrials sector.
Percentage of fund assets in the energy sector.
Percentage of fund assets in the healthcare sector.
{
"task_id": "07160947-0022-0020-0000-7e0ea4d0b7f7",
"status_code": 20000,
"status_message": "OK",
"live": true,
"cost": 0.0004,
"data": {
"symbol": "SPY",
"tag": "just tag"
},
"result": {
"symbol": "SPY",
"cash_position": 0.0011,
"stock_position": 0.9989,
"bond_position": 0,
"other_position": 0,
"preferred_position": 0,
"convertible_position": 0,
"price_to_earnings": 0.03691,
"price_to_book_holding": 0.18424,
"price_to_sales": 0.2638,
"price_to_cashflow": 0.04899,
"median_market_cap": null,
"three_year_earnings_growth": null,
"realestate": 0.01809999,
"consumer_cyclical": 0.0989,
"basic_materials": 0.0167,
"consumer_defensive": 0.045,
"technology": 0.39049998,
"communication_services": 0.1064,
"financial_services": 0.1107,
"utilities": 0.0211,
"industrials": 0.0782,
"energy": 0.0313,
"healthcare": 0.083
}
}Notes
- All allocation and sector values represent proportions of the total portfolio.
- Sector weights may not sum to exactly one due to rounding or partial data availability.
- Percentages are expressed as decimal fractions (e.g. 0.25 = 25%)
- Full calculation methodology and field definitions are documented in the Glossary.
