Institutional & Insider Ownership API

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 identifier (ticker symbol).

insiders_percent_held number

Percentage of shares held by insiders.

institutions_percent_held number

Percentage of shares held by institutions.

institutions_float_percent_held number

Percentage of float shares held by institutions.

institutions_count integer

Number of institutional holders.

buy_info_shares integer

Total shares bought by insiders.

sell_info_shares integer

Total shares sold by insiders.

net_info_shares integer

Net insider shares (buys - sells).

net_percent_insider_shares number

Net insider shares, as a fraction of total insider shares.

total_insider_shares integer

Total insider shares held.

Example Response

{
    "task_id": "07160931-0022-0015-0000-094b0eb3698e",
    "status_code": 20000,
    "status_message": "OK",
    "live": true,
    "cost": 0.0004,
    "data": {
        "symbol": "NVDA",
        "tag": "just tag"
    },
    "result": {
        "symbol": "NVDA",
        "insiders_percent_held": 0.03983999,
        "institutions_percent_held": 0.70805,
        "institutions_float_percent_held": 0.73743,
        "institutions_count": 7503,
        "buy_info_shares": 61772597,
        "sell_info_shares": 3148137,
        "net_info_shares": 58624460,
        "net_percent_insider_shares": 0.065,
        "total_insider_shares": 964127936
    }
}

Notes

Percent values are returned as fractions (e.g., 0.69359 = 69.359%).
Full definitions are maintained in the Glossary.