Browse all documentation

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_id 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_covered.

Base URL: https://api.narwhalapi.com. 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

WhatEvery account
Institutions of a companyIncluded
Holdings of an institutionIncluded
Name search and filing listIncluded

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_cursor is charged, and the next page, if empty, is free.
  • Numbers are decimal strings. A field with no value is left out, a list is always present, and a flag such as new_position is sent only when true.
  • A page can end with a next_cursor. Send it back as cursor with the same other parameters. A cursor from another request is 400 invalid_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 its period. Send period to read one quarter only.
  • reported_price is value divided by shares, 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_type is SH for shares and PRN for a principal amount. put_call is sent for an option position.
  • other_managers holds the numbers of the other included managers who share the position. Their names are in other_included_managers on the filings route.
  • shares_change and new_position compare with the institution's previous quarter, and the holdings route sends them.
  • table_entry_total 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.

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_cursor to read every institution.

MCP: tool filings_list_institutional_holders.

Parameters

ParameterWhereRequiredTypeMeaning
company_idpathYesstringThe company id, for example usa:0000320193. A ticker alias such as usa:AAPL is accepted.
periodqueryNodateA report quarter end, for example 2026-06-30. Left out, the newest quarter. A quarter we hold nothing for is 404 period_not_published.
cursorqueryNostringnext_cursor of the previous page, with the same other parameters.
limitqueryNointegerRows per page. Default 100, at most 500.

Response fields

FieldTypeSentMeaning
idstringAlwaysThe company id.
perioddateOptionalThe report quarter end that was served. Left out when the holdings route is asked for a range of quarters.
periodslist of dateAlwaysThe report quarter ends held, newest first.
built_atstringOptionalWhen the file behind the answer was built (UTC).
holderslist of objectAlwaysThe institutions that hold the company, largest value first.
holders[].investor_idstringAlwaysThe institution's id: usa: and its CIK padded to ten digits.
holders[].investorstringOptionalName of the institution, as it files it.
holders[].filing_idstringAlwaysId of the 13F filing the row comes from.
holders[].formstringAlwaysThe form of the filing, for example 13F-HR.
holders[].reportalways "combination"Optionalcombination when the filing is a combination report: it includes positions of other managers.
holders[].amendmentone of restatement, new_holdings, unstatedOptionalWhat an amendment does to the filing it changes: restatement, new_holdings or unstated.
holders[].fileddateAlwaysDay the filing was made.
holders[].issuerstringAlwaysName of the issuer, as the filing prints it.
holders[].classstringOptionalTitle of the class of the security, for example COM.
holders[].valuestringAlwaysValue of the position in US dollars.
holders[].sharesstringAlwaysShares, or the principal amount when shares_type is PRN.
holders[].shares_typeone of SH, PRNOptionalSH for shares, PRN for a principal amount.
holders[].put_callone of Put, CallOptionalPut or Call on an option position. Left out for other positions.
holders[].discretionstringOptionalInvestment discretion as filed: SOLE, DFND (shared, defined) or OTR (shared, other).
holders[].votingobjectAlwaysVoting authority, in shares.
holders[].voting.solestringAlwaysShares with sole voting authority.
holders[].voting.sharedstringAlwaysShares with shared voting authority.
holders[].voting.nonestringAlwaysShares with no voting authority.
holders[].perioddateAlwaysThe report quarter end of this position.
holders[].percent_of_portfoliostringOptionalThe position's value as a percent of the filing's table_value_total.
holders[].reported_pricestringOptionalPrice per share worked out from value and shares. See the limits above.
holders[].other_managerslist of stringAlwaysNumbers of the other included managers who share the position.
holders[].percent_of_outstandingstringOptionalThe position as a percent of the company's shares outstanding. Plain share positions only.
holders[].outstanding_as_ofdateOptionalThe date of the share count behind percent_of_outstanding.
holders[].confidential_omittedalways trueOptionalTrue when the filer left out positions for which it asked the SEC for confidential treatment.
next_cursorstringAlwaysPass as cursor to read the next page. Always sent; null on the last page.
Request
curl -H "Authorization: Bearer $NARWHAL_API_KEY" \
  "https://api.narwhalapi.com/v1/companies/usa:0000320193/institutions?period=2026-09-30&limit=2"
Example response
{
  "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_period_gte, report_period_gt, report_period_lte and report_period_lt 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_query.

MCP: tool filings_list_investor_holdings.

Parameters

ParameterWhereRequiredTypeMeaning
cikpathYesstringThe institution's CIK, one to ten digits, or its investor_id (usa: and one to ten digits). Leading zeros are optional.
periodqueryNodateOne report quarter end. Left out, the newest quarter. Not together with the range parameters.
report_period_gtequeryNodateOnly quarters ending on or after this day (YYYY-MM-DD).
report_period_gtqueryNodateOnly quarters ending after this day.
report_period_ltequeryNodateOnly quarters ending on or before this day.
report_period_ltqueryNodateOnly quarters ending before this day.
cursorqueryNostringnext_cursor of the previous page, with the same other parameters.
limitqueryNointegerRows per page. Default 100, at most 500.

Response fields

FieldTypeSentMeaning
idstringAlwaysThe institution's id: usa: and its CIK padded to ten digits.
investorstringOptionalName of the institution, as it files it.
perioddateOptionalThe report quarter end that was served. Left out when the holdings route is asked for a range of quarters.
periodslist of dateAlwaysThe report quarter ends held, newest first.
built_atstringOptionalWhen the file behind the answer was built (UTC).
holdingslist of objectAlwaysThe positions, largest value first. A range of quarters lists the newest quarter first.
holdings[].company_idstringOptionalId of the issuer in our company list. Left out when the issuer is not matched to a company.
holdings[].companystringOptionalName of the issuer in our company list.
holdings[].tickerstringOptionalTicker of the issuer in our company list.
holdings[].filing_idstringAlwaysId of the 13F filing the row comes from.
holdings[].formstringAlwaysThe form of the filing, for example 13F-HR.
holdings[].reportalways "combination"Optionalcombination when the filing is a combination report: it includes positions of other managers.
holdings[].amendmentone of restatement, new_holdings, unstatedOptionalWhat an amendment does to the filing it changes: restatement, new_holdings or unstated.
holdings[].fileddateAlwaysDay the filing was made.
holdings[].issuerstringAlwaysName of the issuer, as the filing prints it.
holdings[].classstringOptionalTitle of the class of the security, for example COM.
holdings[].valuestringAlwaysValue of the position in US dollars.
holdings[].sharesstringAlwaysShares, or the principal amount when shares_type is PRN.
holdings[].shares_typeone of SH, PRNOptionalSH for shares, PRN for a principal amount.
holdings[].put_callone of Put, CallOptionalPut or Call on an option position. Left out for other positions.
holdings[].discretionstringOptionalInvestment discretion as filed: SOLE, DFND (shared, defined) or OTR (shared, other).
holdings[].votingobjectAlwaysVoting authority, in shares.
holdings[].voting.solestringAlwaysShares with sole voting authority.
holdings[].voting.sharedstringAlwaysShares with shared voting authority.
holdings[].voting.nonestringAlwaysShares with no voting authority.
holdings[].perioddateAlwaysThe report quarter end of this position.
holdings[].percent_of_portfoliostringOptionalThe position's value as a percent of the filing's table_value_total.
holdings[].reported_pricestringOptionalPrice per share worked out from value and shares. See the limits above.
holdings[].other_managerslist of stringAlwaysNumbers of the other included managers who share the position.
holdings[].shares_changestringOptionalChange in shares since the institution's previous quarter. Negative when it sold.
holdings[].new_positionalways trueOptionalTrue when the institution held none of it in the previous quarter.
holdings[].confidential_omittedalways trueOptionalTrue when the filer left out positions for which it asked the SEC for confidential treatment.
next_cursorstringAlwaysPass as cursor to read the next page. Always sent; null on the last page.
Request
curl -H "Authorization: Bearer $NARWHAL_API_KEY" \
  "https://api.narwhalapi.com/v1/investors/1067983/holdings?limit=2"
Example response
{
  "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_id, which is accepted as the cik on the other routes.

Pass investor_id, or only its digits, as cik on the other routes.

MCP: tool filings_search_investors.

Parameters

ParameterWhereRequiredTypeMeaning
namequeryYesstringPart of the institution's name, any case, 2 to 100 characters.
cursorqueryNostringnext_cursor of the previous page, with the same other parameters.
limitqueryNointegerRows per page. Default 100, at most 500.

Response fields

FieldTypeSentMeaning
investorslist of objectAlwaysThe institutions whose name holds the text.
investors[].investor_idstringAlwaysThe institution's id: usa: and its CIK padded to ten digits.
investors[].namestringAlwaysName of the institution, as it files it.
investors[].latest_perioddateAlwaysThe report quarter end of the institution's newest filing.
next_cursorstringAlwaysPass as cursor to read the next page. Always sent; null on the last page.
Request
curl -H "Authorization: Bearer $NARWHAL_API_KEY" \
  "https://api.narwhalapi.com/v1/investors?name=berkshire&limit=2"
Example response
{
  "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_list_investor_filings.

Parameters

ParameterWhereRequiredTypeMeaning
cikpathYesstringThe institution's CIK, one to ten digits, or its investor_id (usa: and one to ten digits). Leading zeros are optional.
report_period_gtequeryNodateOnly quarters ending on or after this day (YYYY-MM-DD).
report_period_gtqueryNodateOnly quarters ending after this day.
report_period_ltequeryNodateOnly quarters ending on or before this day.
report_period_ltqueryNodateOnly quarters ending before this day.
formqueryNostringOnly filings on this form: 13F-HR, 13F-HR/A, 13F-NT, 13F-NT/A or 13F-CTR.
cursorqueryNostringnext_cursor of the previous page, with the same other parameters.
limitqueryNointegerRows per page. Default 100, at most 500.

Response fields

FieldTypeSentMeaning
idstringAlwaysThe institution's id: usa: and its CIK padded to ten digits.
investorstringOptionalName of the institution, as it files it.
filingslist of objectAlwaysThe 13F filings, newest report quarter first.
filings[].filing_idstringAlwaysId of the 13F filing the row comes from.
filings[].formstringAlwaysThe form of the filing, for example 13F-HR.
filings[].perioddateAlwaysThe report quarter end the filing covers.
filings[].fileddateAlwaysDay the filing was made.
filings[].report_typestringOptionalThe report type printed on the cover page, for example 13F HOLDINGS REPORT.
filings[].amendmentone of restatement, new_holdings, unstatedOptionalWhat an amendment does to the filing it changes: restatement, new_holdings or unstated.
filings[].amendment_nostringOptionalThe amendment number printed on the cover page.
filings[].file_numberstringOptionalThe SEC file number printed on the cover page.
filings[].crdstringOptionalThe CRD number printed on the cover page.
filings[].table_entry_totalintegerOptionalNumber of entries the filer declared in its table.
filings[].table_value_totalstringOptionalTotal value the filer declared for its table, in US dollars.
filings[].other_included_managers_countintegerOptionalHow many other included managers the filer declared.
filings[].other_included_managerslist of objectAlwaysThe other managers whose positions the filing includes.
filings[].other_included_managers[].sequenceintegerAlwaysThe manager's number. A position's other_managers refers to it.
filings[].other_included_managers[].investor_idstringOptionalThe manager's id, when it files a 13F of its own.
filings[].other_included_managers[].namestringOptionalName of the manager.
filings[].other_included_managers[].file_numberstringOptionalThe manager's SEC file number.
filings[].other_included_managers[].crdstringOptionalThe manager's CRD number.
filings[].confidential_omittedalways trueOptionalTrue when the filer left out positions for which it asked the SEC for confidential treatment.
filings[].noticealways trueOptionalTrue on a notice report, which lists no positions of its own.
next_cursorstringAlwaysPass as cursor to read the next page. Always sent; null on the last page.
Request
curl -H "Authorization: Bearer $NARWHAL_API_KEY" \
  "https://api.narwhalapi.com/v1/investors/1067983/filings?limit=1"
Example response
{
  "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_id. See Errors and credits for the shape and the credit headers. Failed requests are not charged.

CodeStatusMeaning
invalid_query400A parameter is missing, unknown, repeated or outside its range.
invalid_cursor400The cursor is not one this request returned, or it comes from a different request.
company_not_found404No company matches the id.
investor_not_found404No 13F filer matches the CIK.
period_not_published404No 13F data is held for the quarter asked.
not_covered404The market, country or company is not covered yet.
insufficient_credits402Your credit balance is less than the request costs.
company_data_unavailable503The filings behind this route cannot be read right now. Try again shortly.

Was this page helpful?