Skip to main content
GET
/
institutional-holdings
Get 13F institutional holdings
curl --request GET \
  --url https://api.financialdatasets.ai/institutional-holdings \
  --header 'X-API-KEY: <api-key>'
{
  "ticker": "<string>",
  "filer_cik": "<string>",
  "institutional_holdings": [
    {
      "ticker": "<string>",
      "name_of_issuer": "<string>",
      "cusip": "<string>",
      "report_period": "2023-12-25",
      "filing_date": "2023-12-25",
      "form_type": "13F-HR",
      "accession_number": "<string>",
      "title_of_class": "<string>",
      "put_call": null,
      "shares": 123,
      "value_usd": 123,
      "reported_price": 123,
      "filer_cik": "<string>",
      "filer_name": "<string>",
      "subsidiaries": [
        {
          "row_num": 123,
          "shares": 123,
          "value_usd": 123,
          "shares_principal_amount_type": "SH",
          "investment_discretion": "SOLE",
          "voting_authority_sole": 123,
          "voting_authority_shared": 123,
          "voting_authority_none": 123,
          "other_managers": [
            "<string>"
          ]
        }
      ]
    }
  ]
}

Documentation Index

Fetch the complete documentation index at: https://docs.financialdatasets.ai/llms.txt

Use this file to discover all available pages before exploring further.

​
Overview

Get the institutional investors who currently hold a given ticker, sorted by position size. Pulled directly from SEC Form 13F filings; results are sorted by position value descending. Use this to answer “who currently owns AAPL?” and at what size, with one row per filer and full subsidiary detail preserved. To get started, please create an account and grab your API key at financialdatasets.ai. You will use the API key to authenticate your API requests.

​
The “current” definition

Without a report_period filter, this endpoint returns one position per institutional filer whose most recent 13F currently includes the ticker. Filers who held the ticker historically but dropped it in their latest 13F are excluded. This is the strict “current holders” view. If you need historical snapshots, pass report_period filters (see below) to opt into the historical view.

​
Find available tickers

To discover which tickers appear across 13F filings, hit the helper endpoint:
Tickers
import requests

# free endpoint, no API key required
url = 'https://api.financialdatasets.ai/institutional-holdings/tickers/'
response = requests.get(url)

tickers = response.json().get('tickers')
print(f'{len(tickers)} tickers held by 13F filers')
This endpoint is free and does not require an API key.

​
Filtering the Data

ticker is required. By default, the response is the strict “currently owns” view described above. To see historical holders, pass report_period filters:
  • report_period_lte
  • report_period_lt
  • report_period_gte
  • report_period_gt
  • report_period
When any report_period filter is provided, the endpoint returns every matching row in the period range (no current-owners filter is applied). By default, limit is 10 (max 200).

​
Subsidiaries

When a 13F filer reports the same security across multiple voting-authority splits (e.g., parent + subsidiary advisors), the top-level position aggregates the splits and a subsidiaries array preserves each underlying row. The subsidiaries field is omitted when there is only one underlying row.

​
Examples

import requests

# add your API key to the headers
headers = {
    "X-API-KEY": "your_api_key_here"
}

# set your query params
ticker = 'AAPL'             # held security ticker
limit = 100                 # number of holders to return

# create the URL
url = (
    f'https://api.financialdatasets.ai/institutional-holdings/'
    f'?ticker={ticker}'
    f'&limit={limit}'
)

# make API request
response = requests.get(url, headers=headers)

# parse institutional_holdings from the response
institutional_holdings = response.json().get('institutional_holdings')

Authorizations

​
X-API-KEY
string
header
required

API key for authentication.

Query Parameters

​
filer_cik
string

The 10-digit zero-padded SEC CIK of the institutional filer. Mutually exclusive with ticker.

​
ticker
string

The held security's ticker symbol. Mutually exclusive with filer_cik. Without a report_period filter, returns one position per institutional filer whose most recent 13F currently includes this ticker.

​
limit
integer
default:10

The maximum number of positions to return (default: 10, max: 200).

Required range: x <= 200
​
report_period
string<date>

Filter by exact report period date in YYYY-MM-DD format.

​
report_period_gte
string<date>

Filter by report period greater than or equal to date in YYYY-MM-DD format.

​
report_period_lte
string<date>

Filter by report period less than or equal to date in YYYY-MM-DD format.

​
report_period_gt
string<date>

Filter by report period greater than date in YYYY-MM-DD format.

​
report_period_lt
string<date>

Filter by report period less than date in YYYY-MM-DD format.

Response

Institutional holdings response

Envelope keyed by ticker (ticker mode) or filer_cik (filer mode), with the position list under institutional_holdings.

​
ticker
string

Echoed back when the request used ?ticker=... mode.

​
filer_cik
string

Echoed back when the request used ?filer_cik=... mode.

​
institutional_holdings
object[]