Institutional holders API reference
Institutions that hold a company and what each institution holds, from Form 13F
Overview
Form 13F is the quarterly report of the US stock and option positions held by institutional investment managers that manage at least $100 million. These routes show which institutions hold a company and what one institution holds, one report quarter at a time. Every request needs a Bearer key, and REST and MCP draw on one credit balance.
Four routes. The first lists the institutions that hold a company. The second lists what one institution holds. The third finds an institution by name. The fourth lists the 13F filings of one institution, with the figures on each cover page. A company is addressed by its Filings API id, for example usa:0000320193. An institution is addressed by its own CIK, and its investor_ is usa: and the CIK padded to ten digits.
A quarter is a report quarter end, for example 2026-06-30. Left out, the newest quarter is served. Each row is one position and names the quarter and the filing it comes from. Values are in US dollars, whatever unit the filing used.
History starts with the report quarter ending 30 September 2021. periods lists the quarters held. A quarter listed before that is read only in part, so its holder count is partial and it is not a full list of holders.
The US is the only country covered. A company of another country is 404 not_.
Base URL: https:/. Each route below is an MCP tool of its own, with the same parameters.
Holders of more than 5% are on the large holders page, and insiders on the insider trades page.
Company ids are the ones the Filings API returns from company search.
What every account gets
| What | Every account |
|---|---|
| Institutions of a company | Included |
| Holdings of an institution | Included |
| Name search and filing list | Included |
See pricing for what a call costs. A request is charged at the price of its API unless a route says otherwise.
- Billed at the Companies price, $10 per 1,000 calls. Each successful answer is one call, whatever the number of rows. An empty page and a search with no hits are free, and so are errors. A page with rows and a
next_is charged, and the next page, if empty, is free.cursor - Numbers are decimal strings. A field with no value is left out, a list is always present, and a flag such as
new_is sent only when true.position - A page can end with a
next_. Send it back ascursor cursorwith the same other parameters. A cursor from another request is 400invalid_.cursor - Without
period, the institutions route serves the newest quarter and also lists an institution whose newest report is from an earlier quarter, with that quarter in itsperiod. Sendperiodto read one quarter only. reported_isprice valuedivided byshares, as the filing states them. It is sent for filings made from 3 January 2023, when filings began to state values in dollars, and left out for principal amounts and for a position with no shares. Earlier filings stated values in thousands, which Narwhal sends in dollars.shares_istype SHfor shares andPRNfor a principal amount.put_is sent for an option position.call other_holds the numbers of the other included managers who share the position. Their names are inmanagers other_on the filings route.included_ managers shares_andchange new_compare with the institution's previous quarter, and the holdings route sends them.position table_is what the filer declared on its cover page. It is wrong in about 2 filings in 100, so count the rows if you need the true number.entry_ total
Endpoints
Every route is a GET and needs your key in the Authorization: Bearer header. The examples show the shape of an answer, not live data.
List the institutions that hold a company
GET /v1/companies/{company_id}/institutions
The institutions that reported a position in a company on Form 13F, largest value first. Each row is one position of one institution, for one report quarter.
Rows are largest value first. Page with next_ to read every institution.
MCP: tool filings_.
Parameters
| Parameter | Where | Required | Type | Meaning |
|---|---|---|---|---|
company_ | path | Yes | string | The company id, for example usa:0000320193. A ticker alias such as usa:AAPL is accepted. |
period | query | No | date | A report quarter end, for example 2026-06-30. Left out, the newest quarter. A quarter we hold nothing for is 404 period_. |
cursor | query | No | string | next_ of the previous page, with the same other parameters. |
limit | query | No | integer | Rows per page. Default 100, at most 500. |
Response fields
| Field | Type | Sent | Meaning |
|---|---|---|---|
id | string | Always | The company id. |
period | date | Optional | The report quarter end that was served. Left out when the holdings route is asked for a range of quarters. |
periods | list of date | Always | The report quarter ends held, newest first. |
built_ | string | Optional | When the file behind the answer was built (UTC). |
holders | list of object | Always | The institutions that hold the company, largest value first. |
holders[].investor_ | string | Always | The institution's id: usa: and its CIK padded to ten digits. |
holders[].investor | string | Optional | Name of the institution, as it files it. |
holders[].filing_ | string | Always | Id of the 13F filing the row comes from. |
holders[].form | string | Always | The form of the filing, for example 13F-HR. |
holders[].report | always "combination" | Optional | combination when the filing is a combination report: it includes positions of other managers. |
holders[].amendment | one of restatement, new_holdings, unstated | Optional | What an amendment does to the filing it changes: restatement, new_ or unstated. |
holders[].filed | date | Always | Day the filing was made. |
holders[].issuer | string | Always | Name of the issuer, as the filing prints it. |
holders[].class | string | Optional | Title of the class of the security, for example COM. |
holders[].value | string | Always | Value of the position in US dollars. |
holders[].shares | string | Always | Shares, or the principal amount when shares_ is PRN. |
holders[].shares_ | one of SH, PRN | Optional | SH for shares, PRN for a principal amount. |
holders[].put_ | one of Put, Call | Optional | Put or Call on an option position. Left out for other positions. |
holders[].discretion | string | Optional | Investment discretion as filed: SOLE, DFND (shared, defined) or OTR (shared, other). |
holders[].voting | object | Always | Voting authority, in shares. |
holders[].voting.sole | string | Always | Shares with sole voting authority. |
holders[].voting.shared | string | Always | Shares with shared voting authority. |
holders[].voting.none | string | Always | Shares with no voting authority. |
holders[].period | date | Always | The report quarter end of this position. |
holders[].percent_ | string | Optional | The position's value as a percent of the filing's table_. |
holders[].reported_ | string | Optional | Price per share worked out from value and shares. See the limits above. |
holders[].other_ | list of string | Always | Numbers of the other included managers who share the position. |
holders[].percent_ | string | Optional | The position as a percent of the company's shares outstanding. Plain share positions only. |
holders[].outstanding_ | date | Optional | The date of the share count behind percent_. |
holders[].confidential_ | always true | Optional | True when the filer left out positions for which it asked the SEC for confidential treatment. |
next_ | string | Always | Pass as cursor to read the next page. Always sent; null on the last page. |
curl -H "Authorization: Bearer $NARWHAL_API_KEY" \
"https://api.narwhalapi.com/v1/companies/usa:0000320193/institutions?period=2026-09-30&limit=2"{
"id": "usa:0000320193",
"period": "2026-09-30",
"periods": [
"2026-09-30",
"2026-06-30",
"2026-03-31",
"2025-12-31"
],
"built_at": "2026-11-16T03:09:01Z",
"holders": [
{
"investor_id": "usa:0002012383",
"investor": "BlackRock, Inc.",
"filing_id": "usa:0002012383:0002012383-26-003985",
"form": "13F-HR",
"report": "combination",
"filed": "2026-11-13",
"issuer": "APPLE INC",
"class": "COM",
"value": "385329896040",
"shares": "1157077341",
"shares_type": "SH",
"discretion": "SOLE",
"voting": {
"sole": "1037578760",
"shared": "0",
"none": "119498580"
},
"period": "2026-09-30",
"percent_of_portfolio": "5.6736",
"reported_price": "333.02",
"other_managers": [
"2",
"3",
"4"
]
},
{
"investor_id": "usa:0002100119",
"investor": "VANGUARD CAPITAL MANAGEMENT LLC",
"filing_id": "usa:0002100119:0002100119-26-001711",
"form": "13F-HR",
"filed": "2026-11-13",
"issuer": "APPLE INC",
"class": "COM",
"value": "318109956628",
"shares": "955227784",
"shares_type": "SH",
"discretion": "DFND",
"voting": {
"sole": "0",
"shared": "0",
"none": "955227784"
},
"period": "2026-09-30",
"percent_of_portfolio": "6.6794",
"reported_price": "333.02",
"other_managers": []
}
],
"next_cursor": "eyJrIjoidUdkUmJZRS1vV0Mw…"
}List what an institution holds
GET /v1/investors/{cik}/holdings
What one institution reported on Form 13F, largest value first, for one quarter or for a range of quarters. cik is the institution's own CIK.
report_, report_, report_ and report_ read many quarters in one call, newest quarter first and largest value first inside a quarter. period is then not sent. Asking for period and a range together is 400 invalid_.
MCP: tool filings_.
Parameters
| Parameter | Where | Required | Type | Meaning |
|---|---|---|---|---|
cik | path | Yes | string | The institution's CIK, one to ten digits, or its investor_ (usa: and one to ten digits). Leading zeros are optional. |
period | query | No | date | One report quarter end. Left out, the newest quarter. Not together with the range parameters. |
report_ | query | No | date | Only quarters ending on or after this day (YYYY-MM-DD). |
report_ | query | No | date | Only quarters ending after this day. |
report_ | query | No | date | Only quarters ending on or before this day. |
report_ | query | No | date | Only quarters ending before this day. |
cursor | query | No | string | next_ of the previous page, with the same other parameters. |
limit | query | No | integer | Rows per page. Default 100, at most 500. |
Response fields
| Field | Type | Sent | Meaning |
|---|---|---|---|
id | string | Always | The institution's id: usa: and its CIK padded to ten digits. |
investor | string | Optional | Name of the institution, as it files it. |
period | date | Optional | The report quarter end that was served. Left out when the holdings route is asked for a range of quarters. |
periods | list of date | Always | The report quarter ends held, newest first. |
built_ | string | Optional | When the file behind the answer was built (UTC). |
holdings | list of object | Always | The positions, largest value first. A range of quarters lists the newest quarter first. |
holdings[].company_ | string | Optional | Id of the issuer in our company list. Left out when the issuer is not matched to a company. |
holdings[].company | string | Optional | Name of the issuer in our company list. |
holdings[].ticker | string | Optional | Ticker of the issuer in our company list. |
holdings[].filing_ | string | Always | Id of the 13F filing the row comes from. |
holdings[].form | string | Always | The form of the filing, for example 13F-HR. |
holdings[].report | always "combination" | Optional | combination when the filing is a combination report: it includes positions of other managers. |
holdings[].amendment | one of restatement, new_holdings, unstated | Optional | What an amendment does to the filing it changes: restatement, new_ or unstated. |
holdings[].filed | date | Always | Day the filing was made. |
holdings[].issuer | string | Always | Name of the issuer, as the filing prints it. |
holdings[].class | string | Optional | Title of the class of the security, for example COM. |
holdings[].value | string | Always | Value of the position in US dollars. |
holdings[].shares | string | Always | Shares, or the principal amount when shares_ is PRN. |
holdings[].shares_ | one of SH, PRN | Optional | SH for shares, PRN for a principal amount. |
holdings[].put_ | one of Put, Call | Optional | Put or Call on an option position. Left out for other positions. |
holdings[].discretion | string | Optional | Investment discretion as filed: SOLE, DFND (shared, defined) or OTR (shared, other). |
holdings[].voting | object | Always | Voting authority, in shares. |
holdings[].voting.sole | string | Always | Shares with sole voting authority. |
holdings[].voting.shared | string | Always | Shares with shared voting authority. |
holdings[].voting.none | string | Always | Shares with no voting authority. |
holdings[].period | date | Always | The report quarter end of this position. |
holdings[].percent_ | string | Optional | The position's value as a percent of the filing's table_. |
holdings[].reported_ | string | Optional | Price per share worked out from value and shares. See the limits above. |
holdings[].other_ | list of string | Always | Numbers of the other included managers who share the position. |
holdings[].shares_ | string | Optional | Change in shares since the institution's previous quarter. Negative when it sold. |
holdings[].new_ | always true | Optional | True when the institution held none of it in the previous quarter. |
holdings[].confidential_ | always true | Optional | True when the filer left out positions for which it asked the SEC for confidential treatment. |
next_ | string | Always | Pass as cursor to read the next page. Always sent; null on the last page. |
curl -H "Authorization: Bearer $NARWHAL_API_KEY" \
"https://api.narwhalapi.com/v1/investors/1067983/holdings?limit=2"{
"id": "usa:0001067983",
"investor": "Berkshire Hathaway Inc",
"period": "2026-06-30",
"periods": [
"2026-06-30",
"2026-03-31",
"2025-12-31",
"2025-09-30"
],
"built_at": "2026-11-14T14:10:32Z",
"holdings": [
{
"company_id": "usa:0000320193",
"company": "Apple Inc.",
"ticker": "AAPL",
"filing_id": "usa:0001067983:0001193125-26-352200",
"form": "13F-HR",
"filed": "2026-08-14",
"issuer": "APPLE INC",
"class": "COM",
"value": "65950296923",
"shares": "227917808",
"shares_type": "SH",
"discretion": "DFND",
"voting": {
"sole": "227917808",
"shared": "0",
"none": "0"
},
"period": "2026-06-30",
"percent_of_portfolio": "22.0383",
"reported_price": "289.36",
"other_managers": [
"1",
"2",
"4"
],
"shares_change": "0"
},
{
"company_id": "usa:0000004962",
"company": "AMERICAN EXPRESS CO",
"ticker": "AXP",
"filing_id": "usa:0001067983:0001193125-26-352200",
"form": "13F-HR",
"filed": "2026-08-14",
"issuer": "AMERICAN EXPRESS CO",
"class": "COM",
"value": "51282319275",
"shares": "151610700",
"shares_type": "SH",
"discretion": "DFND",
"voting": {
"sole": "151610700",
"shared": "0",
"none": "0"
},
"period": "2026-06-30",
"percent_of_portfolio": "17.1367",
"reported_price": "338.25",
"other_managers": [
"4",
"11",
"13"
],
"shares_change": "0"
}
],
"next_cursor": "eyJrIjoiT3BDSFhISGJ0Y25T…"
}Search institutions by name
GET /v1/investors
Find an institution that files Form 13F by part of its name. Returns the investor_, which is accepted as the cik on the other routes.
Pass investor_, or only its digits, as cik on the other routes.
MCP: tool filings_.
Parameters
| Parameter | Where | Required | Type | Meaning |
|---|---|---|---|---|
name | query | Yes | string | Part of the institution's name, any case, 2 to 100 characters. |
cursor | query | No | string | next_ of the previous page, with the same other parameters. |
limit | query | No | integer | Rows per page. Default 100, at most 500. |
Response fields
| Field | Type | Sent | Meaning |
|---|---|---|---|
investors | list of object | Always | The institutions whose name holds the text. |
investors[].investor_ | string | Always | The institution's id: usa: and its CIK padded to ten digits. |
investors[].name | string | Always | Name of the institution, as it files it. |
investors[].latest_ | date | Always | The report quarter end of the institution's newest filing. |
next_ | string | Always | Pass as cursor to read the next page. Always sent; null on the last page. |
curl -H "Authorization: Bearer $NARWHAL_API_KEY" \
"https://api.narwhalapi.com/v1/investors?name=berkshire&limit=2"{
"investors": [
{
"investor_id": "usa:0000949012",
"name": "BERKSHIRE ASSET MANAGEMENT LLC/PA",
"latest_period": "2026-09-30"
},
{
"investor_id": "usa:0001133742",
"name": "BERKSHIRE CAPITAL HOLDINGS INC",
"latest_period": "2026-09-30"
}
],
"next_cursor": "eyJrIjoiajJwemRIcXJfZnNn…"
}List the 13F filings of an institution
GET /v1/investors/{cik}/filings
The cover page of each 13F filing an institution made, newest report quarter first: form, report type, filing date, entry count, value total and the other managers included.
Use form to keep one form, for example 13F-HR, and the range parameters to keep some quarters.
MCP: tool filings_.
Parameters
| Parameter | Where | Required | Type | Meaning |
|---|---|---|---|---|
cik | path | Yes | string | The institution's CIK, one to ten digits, or its investor_ (usa: and one to ten digits). Leading zeros are optional. |
report_ | query | No | date | Only quarters ending on or after this day (YYYY-MM-DD). |
report_ | query | No | date | Only quarters ending after this day. |
report_ | query | No | date | Only quarters ending on or before this day. |
report_ | query | No | date | Only quarters ending before this day. |
form | query | No | string | Only filings on this form: 13F-HR, 13F-HR/, 13F-NT, 13F-NT/ or 13F-CTR. |
cursor | query | No | string | next_ of the previous page, with the same other parameters. |
limit | query | No | integer | Rows per page. Default 100, at most 500. |
Response fields
| Field | Type | Sent | Meaning |
|---|---|---|---|
id | string | Always | The institution's id: usa: and its CIK padded to ten digits. |
investor | string | Optional | Name of the institution, as it files it. |
filings | list of object | Always | The 13F filings, newest report quarter first. |
filings[].filing_ | string | Always | Id of the 13F filing the row comes from. |
filings[].form | string | Always | The form of the filing, for example 13F-HR. |
filings[].period | date | Always | The report quarter end the filing covers. |
filings[].filed | date | Always | Day the filing was made. |
filings[].report_ | string | Optional | The report type printed on the cover page, for example 13F HOLDINGS REPORT. |
filings[].amendment | one of restatement, new_holdings, unstated | Optional | What an amendment does to the filing it changes: restatement, new_ or unstated. |
filings[].amendment_ | string | Optional | The amendment number printed on the cover page. |
filings[].file_ | string | Optional | The SEC file number printed on the cover page. |
filings[].crd | string | Optional | The CRD number printed on the cover page. |
filings[].table_ | integer | Optional | Number of entries the filer declared in its table. |
filings[].table_ | string | Optional | Total value the filer declared for its table, in US dollars. |
filings[].other_ | integer | Optional | How many other included managers the filer declared. |
filings[].other_ | list of object | Always | The other managers whose positions the filing includes. |
filings[].other_ | integer | Always | The manager's number. A position's other_ refers to it. |
filings[].other_ | string | Optional | The manager's id, when it files a 13F of its own. |
filings[].other_ | string | Optional | Name of the manager. |
filings[].other_ | string | Optional | The manager's SEC file number. |
filings[].other_ | string | Optional | The manager's CRD number. |
filings[].confidential_ | always true | Optional | True when the filer left out positions for which it asked the SEC for confidential treatment. |
filings[].notice | always true | Optional | True on a notice report, which lists no positions of its own. |
next_ | string | Always | Pass as cursor to read the next page. Always sent; null on the last page. |
curl -H "Authorization: Bearer $NARWHAL_API_KEY" \
"https://api.narwhalapi.com/v1/investors/1067983/filings?limit=1"{
"id": "usa:0001067983",
"investor": "Berkshire Hathaway Inc",
"filings": [
{
"filing_id": "usa:0001067983:0001193125-26-352200",
"form": "13F-HR",
"period": "2026-06-30",
"filed": "2026-08-14",
"report_type": "13F HOLDINGS REPORT",
"file_number": "028-04545",
"table_entry_total": 89,
"table_value_total": "299253556246",
"other_included_managers_count": 14,
"other_included_managers": [
{
"sequence": 1,
"name": "Berkshire Hathaway Homestate Insurance Co.",
"file_number": "28-2226"
},
{
"sequence": 2,
"name": "Berkshire Hathaway Life Insurance Co of Nebraska",
"file_number": "28-5678"
}
]
}
],
"next_cursor": "eyJrIjoiYzZtVkdUQVZ1TFJB…"
}Errors
Errors use the shared problem shape with a request_. See Errors and credits for the shape and the credit headers. Failed requests are not charged.
| Code | Status | Meaning |
|---|---|---|
invalid_ | 400 | A parameter is missing, unknown, repeated or outside its range. |
invalid_ | 400 | The cursor is not one this request returned, or it comes from a different request. |
company_ | 404 | No company matches the id. |
investor_ | 404 | No 13F filer matches the CIK. |
period_ | 404 | No 13F data is held for the quarter asked. |
not_ | 404 | The market, country or company is not covered yet. |
insufficient_ | 402 | Your credit balance is less than the request costs. |
company_ | 503 | The filings behind this route cannot be read right now. Try again shortly. |
Was this page helpful?