> ## 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.
# Owners (by ticker)
> Get the institutional investors who currently hold a given stock, sourced direct from SEC 13F filings.
### 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](https://financialdatasets.ai).
You will use the API key to authenticate your API requests.
### Coverage
| Tickers | Years of Coverage | Updated |
| ------- | ----------------- | ------- |
| 18,000+ | 5+ years | Daily |
### 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:
```python Tickers theme={"theme":{"light":"vitesse-light","dark":"vitesse-dark"}}
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')
```
### 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
```python Current holders theme={"theme":{"light":"vitesse-light","dark":"vitesse-dark"}}
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')
```
```python Historical range theme={"theme":{"light":"vitesse-light","dark":"vitesse-dark"}}
import requests
# add your API key to the headers
headers = {
"X-API-KEY": "your_api_key_here"
}
# set your query params
ticker = 'AAPL'
limit = 200
report_period_lte = '2025-12-31' # end date
report_period_gte = '2024-01-01' # start date
# create the URL
url = (
f'https://api.financialdatasets.ai/institutional-holdings/'
f'?ticker={ticker}'
f'&limit={limit}'
f'&report_period_lte={report_period_lte}'
f'&report_period_gte={report_period_gte}'
)
# make API request
response = requests.get(url, headers=headers)
# parse institutional_holdings from the response
institutional_holdings = response.json().get('institutional_holdings')
```
## OpenAPI
````yaml GET /institutional-holdings
openapi: 3.0.1
info:
title: Financial Datasets API
description: >-
Stock market API with real-time and historical financial data for 27,000+
tickers over 30+ years. Financial statements, equity prices, insider trades,
SEC filings, and more.
version: 1.0.0
license:
name: MIT
url: https://opensource.org/licenses/MIT
contact:
name: API Support
url: mailto:support@financialdatasets.ai
email: support@financialdatasets.ai
termsOfService: https://financialdatasets.ai/terms-of-use
servers:
- url: https://api.financialdatasets.ai/
description: Production server
security:
- X-API-KEY: []
tags:
- name: Financial Statements
description: Access to income statements, balance sheets, and cash flow statements
- name: Market Data
description: Real-time and historical price data
- name: Company Information
description: Company facts like ticker, name, and description
- name: Earnings
description: Earnings data and related information
- name: News
description: Real-time and historical news articles
- name: SEC Filings
description: SEC filings and regulatory documents
- name: Insider Trades
description: Insider trading activity and transactions
- name: Activist Ownership
description: Activist stakes from SEC Schedule 13D filings, in real time
- name: Beneficial Ownership
description: >-
Holders of more than 5% of a company's shares, from SEC Schedules 13D and
13G
- name: Insider Ownership
description: Insider ownership statements from SEC Forms 3 and 5
- name: Institutional Holdings
description: SEC-direct 13F equity holdings of institutional investment managers
- name: Index Funds
description: >-
ETF and index-fund holdings, weights, and the funds that hold a given
security
- name: Financial Metrics
description: Financial ratios, metrics, and key performance indicators
- name: Macroeconomics
description: Real-time and historical macroeconomic data like interest rates
- name: KPIs
description: Sector-specific operational KPIs extracted from earnings releases.
paths:
/institutional-holdings:
get:
tags:
- Institutional Holdings
summary: Get 13F institutional holdings
description: >-
Query 13F institutional holdings by filer CIK or by held ticker. Provide
exactly one of `filer_cik` or `ticker`. When no `report_period` filter
is supplied, `?filer_cik=...` returns the filer's most recent 13F and
`?ticker=...` returns one position per institutional filer whose most
recent 13F currently includes the ticker (filers who have since dropped
the position are excluded).
operationId: getInstitutionalHoldings
parameters:
- name: filer_cik
in: query
description: >-
The 10-digit zero-padded SEC CIK of the institutional filer.
Mutually exclusive with `ticker`.
schema:
type: string
- name: ticker
in: query
description: >-
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.
schema:
type: string
- name: limit
in: query
description: 'The maximum number of positions to return (default: 10, max: 200).'
required: false
schema:
type: integer
default: 10
maximum: 200
- $ref: '#/components/parameters/ReportPeriod'
- $ref: '#/components/parameters/ReportPeriodGte'
- $ref: '#/components/parameters/ReportPeriodLte'
- $ref: '#/components/parameters/ReportPeriodGt'
- $ref: '#/components/parameters/ReportPeriodLt'
responses:
'200':
description: Institutional holdings response
content:
application/json:
schema:
$ref: '#/components/schemas/InstitutionalHoldingsResponse'
'400':
$ref: '#/components/responses/BadRequestError'
'401':
$ref: '#/components/responses/UnauthorizedError'
'402':
$ref: '#/components/responses/PaymentRequiredError'
'404':
$ref: '#/components/responses/NotFoundError'
components:
parameters:
ReportPeriod:
name: report_period
in: query
description: Filter by exact report period date in YYYY-MM-DD format.
required: false
schema:
type: string
format: date
ReportPeriodGte:
name: report_period_gte
in: query
description: >-
Filter by report period greater than or equal to date in YYYY-MM-DD
format.
required: false
schema:
type: string
format: date
ReportPeriodLte:
name: report_period_lte
in: query
description: Filter by report period less than or equal to date in YYYY-MM-DD format.
required: false
schema:
type: string
format: date
ReportPeriodGt:
name: report_period_gt
in: query
description: Filter by report period greater than date in YYYY-MM-DD format.
required: false
schema:
type: string
format: date
ReportPeriodLt:
name: report_period_lt
in: query
description: Filter by report period less than date in YYYY-MM-DD format.
required: false
schema:
type: string
format: date
schemas:
InstitutionalHoldingsResponse:
type: object
description: >-
Envelope keyed by `ticker` (ticker mode) or `filer_cik` (filer mode),
with the position list under `institutional_holdings`.
properties:
ticker:
type: string
description: Echoed back when the request used `?ticker=...` mode.
filer_cik:
type: string
description: Echoed back when the request used `?filer_cik=...` mode.
institutional_holdings:
type: array
items:
$ref: '#/components/schemas/InstitutionalHolding'
InstitutionalHolding:
type: object
description: >-
A single position from a 13F filing. When the filer split voting
authority across multiple subsidiary managers, the top-level fields
aggregate shares and value across the splits and the underlying rows
appear in `subsidiaries`.
properties:
ticker:
type: string
description: >-
The ticker symbol of the held security. May be null if the CUSIP
could not be resolved.
name_of_issuer:
type: string
description: Issuer name as reported on the 13F.
cusip:
type: string
description: 9-character CUSIP of the held security.
report_period:
type: string
format: date
description: The reporting period (quarter end) of the filing.
filing_date:
type: string
format: date
description: The date the filing was submitted to the SEC.
form_type:
type: string
enum:
- 13F-HR
- 13F-HR/A
description: The 13F form type (original `13F-HR` or amendment `13F-HR/A`).
accession_number:
type: string
description: The SEC accession number for this filing.
title_of_class:
type: string
description: Security class as reported (e.g., `COM`, `COM CL A`, `PREF`).
put_call:
type: string
nullable: true
enum:
- null
- Put
- Call
description: >-
Set to `Put` or `Call` for option positions; `null` for the
underlying equity.
shares:
type: integer
format: int64
description: Number of shares (or principal amount) held.
value_usd:
type: integer
format: int64
description: Position market value in USD as reported on the 13F.
reported_price:
type: number
nullable: true
description: >-
Per-share price implied by the reported value and shares (the 13F
equivalent of Dataroma's `Reported Price`). May be null when our
price lookup is unavailable for this CUSIP.
filer_cik:
type: string
description: >-
Present only in ticker-mode responses. The 10-digit SEC CIK of the
filer.
filer_name:
type: string
description: Present only in ticker-mode responses. The filer's name.
subsidiaries:
type: array
description: >-
Present only when the position aggregates multiple SEC
information-table rows (voting authority splits). Omitted for
single-row positions.
items:
$ref: '#/components/schemas/InstitutionalHoldingSubsidiary'
ErrorResponse:
type: object
properties:
error:
type: string
description: A short error message.
message:
type: string
description: A more detailed error message.
InstitutionalHoldingSubsidiary:
type: object
description: >-
One SEC information-table row underlying a position (voting-authority
split).
properties:
row_num:
type: integer
description: Zero-indexed row number from the SEC information table.
shares:
type: integer
format: int64
value_usd:
type: integer
format: int64
shares_principal_amount_type:
type: string
enum:
- SH
- PRN
description: '`SH` for shares; `PRN` for principal amount (debt-like instruments).'
investment_discretion:
type: string
enum:
- SOLE
- DFND
- OTR
description: SEC investment-discretion code.
voting_authority_sole:
type: integer
format: int64
voting_authority_shared:
type: integer
format: int64
voting_authority_none:
type: integer
format: int64
other_managers:
type: array
items:
type: string
description: >-
SEC `OtherManagers` identifiers indicating which subsidiary manager
reported this row.
responses:
BadRequestError:
description: Bad request
content:
application/json:
schema:
$ref: '#/components/schemas/ErrorResponse'
example:
error: Bad Request
message: Invalid request parameters
UnauthorizedError:
description: Unauthorized
content:
application/json:
schema:
$ref: '#/components/schemas/ErrorResponse'
example:
error: Unauthorized
message: Invalid API key provided
PaymentRequiredError:
description: The request requires a paid subscription
content:
application/json:
schema:
$ref: '#/components/schemas/ErrorResponse'
example:
error: Payment Required
message: >-
This endpoint requires a paid subscription. Please upgrade your
plan.
NotFoundError:
description: The specified resource was not found
content:
application/json:
schema:
$ref: '#/components/schemas/ErrorResponse'
example:
error: Not Found
message: Ticker XXXX not found
securitySchemes:
X-API-KEY:
type: apiKey
name: X-API-KEY
description: API key for authentication.
in: header
````