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 symbol.
Asset Allocation
High-level allocation across asset classes within the fund.
Cash and cash equivalents allocation.
Equity holdings allocation.
Bond holdings allocation.
Other asset classes allocation.
Preferred securities allocation.
Convertible securities allocation.
Valuation Characteristics (Holdings-weighted)
Aggregated valuation metrics calculated across the fund’s holdings, weighted by position size.
Price to earnings ratio.
Price to book ratio.
Price to sales ratio.
Price to cash flow ratio.
Market Size and Growth Characteristics
Aggregated market-cap and growth indicators derived from the underlying holdings.
Median market capitalization.
Three-year earnings growth.
Sector Allocation
Sector exposure of the fund, expressed as a proportion of total assets.
Real estate sector exposure.
Consumer cyclical sector exposure.
Basic materials sector exposure.
Consumer defensive sector exposure.
Technology sector exposure.
Communication services sector exposure.
Financial services sector exposure.
Utilities sector exposure.
Industrials sector exposure.
Energy sector exposure.
Healthcare sector exposure.
{
"task_id": "e32ae526-2dc5-46e8-af1e-100a2a11d30f",
"status_code": 20000,
"status_message": "OK",
"cost": 0.01,
"data": {
"symbol": "SPY",
"tag": "just tag"
},
"result": {
"symbol": "SPY",
"cash_position": 0.0026,
"stock_position": 0.9974,
"bond_position": 0,
"other_position": 0,
"preferred_position": 0,
"convertible_position": 0,
"price_to_earnings": 0.03622,
"price_to_book_holding": 0.19672,
"price_to_sales": 0.28377,
"price_to_cashflow": 0.05073,
"median_market_cap": null,
"three_year_earnings_growth": null,
"realestate": 0.0183,
"consumer_cyclical": 0.1055,
"basic_materials": 0.0165,
"consumer_defensive": 0.0471,
"technology": 0.3509,
"communication_services": 0.1089,
"financial_services": 0.1313,
"utilities": 0.0225,
"industrials": 0.0749,
"energy": 0.02809999,
"healthcare": 0.0959
}
}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.
