General

Returns a high-level ownership snapshot for an asset, focused on institutional and insider holdings where available.

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

POST
v1/holders/general
symbol stringrequired

Asset identifier (ticker symbol).

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/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.

symbol string

Asset symbol.

insiders_percent_held number

Insiders percent held.

institutions_percent_held number

Institutions percent held.

institutions_float_percent_held number

Institutions float percent held.

institutions_count integer

Institutions count.

buy_info_shares integer

Insider buy shares (aggregated).

sell_info_shares integer

Insider sell shares (aggregated).

net_info_shares integer

Net insider shares (buy - sell).

net_percent_insider_shares number

Net insider shares as % (normalized indicator).

total_insider_shares integer

Total insider shares held.

Example Response
{
    "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.