This endpoint is primarily relevant for stocks and returns insider and institutional ownership percentages, the number of institutions, and aggregated insider transaction flow metrics.
For ETFs and mutual funds, most ownership fields are not applicable and are returned as null.
When to Use This Endpoint
- Display a quick ownership snapshot on an equity profile page.
- Support ownership-focused screening or filters (e.g., “high institutional ownership”).
- Provide context for liquidity/positioning signals in analytics (institutional share, insider flow).
- Power Holders modules (as a top-level summary), alongside the more detailed holders endpoints.
Request Parameters
v1/holders/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/holders/general" \
--header "Content-Type: application/json" \
--header "Authorization: Bearer <API_TOKEN>" \
-d '{
"symbol": "NVDA",
"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/holders/general";
client.DefaultRequestHeaders.Authorization = new AuthenticationHeaderValue("Bearer", "<API_TOKEN>");
client.DefaultRequestHeaders.Accept.Add(new MediaTypeWithQualityHeaderValue("application/json"));
var json = @"{
""symbol"": ""NVDA"",
""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/holders/general",
CURLOPT_RETURNTRANSFER => true,
CURLOPT_CUSTOMREQUEST => "POST",
CURLOPT_HTTPHEADER => [
"Content-Type: application/json",
"Authorization: Bearer <API_TOKEN>"
],
CURLOPT_POSTFIELDS => json_encode(
[
"symbol" => "NVDA",
"tag" => "just tag"
]
)
]);
$response = curl_exec($curl);
curl_close($curl);
echo $response;
import urllib.request
import json
url = "https://api.finimpulse.com/v1/holders/general"
headers = {
"Content-Type": "application/json",
"Authorization": "Bearer <API_TOKEN>"
}
data = {
"symbol": "NVDA",
"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": "NVDA",
"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/holders/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
Returns a single object with the ownership summary fields.
Asset symbol.
Insiders percent held.
Institutions percent held.
Institutions float percent held.
Institutions count.
Insider buy shares (aggregated).
Insider sell shares (aggregated).
Net insider shares (buy - sell).
Net insider shares as % (normalized indicator).
Total insider shares held.
{
"task_id": "9217d708-1152-4971-a019-b0a54253401f",
"status_code": 20000,
"status_message": "OK",
"cost": 0.01,
"data": {
"symbol": "NVDA",
"tag": "just tag"
},
"result": {
"symbol": "NVDA",
"insiders_percent_held": 0.0433,
"institutions_percent_held": 0.69654,
"institutions_float_percent_held": 0.72807,
"institutions_count": 7010,
"buy_info_shares": 4415192,
"sell_info_shares": 7101141,
"net_info_shares": -2685949,
"net_percent_insider_shares": -0.003,
"total_insider_shares": 1052189952
}
}Notes
- Percent values are returned as fractions (e.g., 0.69359 = 69.359%).
- Full definitions are maintained in the Glossary.
