Large holders API reference

Overview

Large holders are the people and firms that own more than 5% of a US company's shares. They report on Schedule 13D, for a holder that may seek control (tagged activist), and on Schedule 13G, for a passive holder (tagged passive), and on amendments to either. Every request needs a Bearer key, and REST and MCP draw on one credit balance.

Four routes cover the large holders of a company, the large stakes of one holder across companies, and two name searches that find a holder or a company to read. A company is addressed by its Filings API id, for example usa:0000320193. A holder is addressed by its CIK.

By default a route answers the current stakes: each holder's latest filing for each class of shares. A stake whose latest filing reports an exit, or that a later filing of the same filer group left out, is not listed. Send history=true to read every filing, newest first.

History starts with filings of October 2024. A holder's stakes page can hold fewer rows than limit and still end with a next_cursor, so keep reading until next_cursor is null. The US is the only country covered.

Base URL: https://api.narwhalapi.com. Each route below is an MCP tool of its own, with the same parameters.

Officers, directors and 10% owners are on the insider trades page.

Company ids are the ones the Filings API returns from company search.

What every account gets

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. Each successful answer is one call, whatever the number of rows, and an empty page is charged too. Errors are not charged. A search with no hits is charged too.
• Numbers are decimal strings. A field with no value is left out, a list is always present, and a flag such as officer is sent only when true.
• A joint filing has one row for each reporting person, and the rows share a filing_id. Each person states the same group figure on their own cover page, so never add shares across the people of one filing. Group the rows by filing_id and read the group's figure from group_total.
• A figure a filing does not give, or that could not be read cleanly, is left out. Nothing is estimated.
• A holder page reads at most 30 company files, so a holder in joint filings across hundreds of companies comes in short pages that end with a cursor.
• A small number of filings we cannot read are left out of the answers. The CUSIP is not part of any answer.

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 large holders of a company

GET /v1/companies/{company_id}/beneficial-owners

Holders of more than 5% of a company's shares, from Schedules 13D and 13G and their amendments. By default each holder's current stake in each class; history lists every filing.

Dates narrow the filings before the latest one of each stake is chosen, so filed_lte gives the large holders of the company as they stood on that day.

MCP: tool filings_list_beneficial_owners.

Parameters

Response fields

curl -H "Authorization: Bearer $NARWHAL_API_KEY" \
  "https://api.narwhalapi.com/v1/companies/usa:0000320193/beneficial-owners?limit=1"

{
  "id": "usa:0000320193",
  "company": "Apple Inc.",
  "owners": [
    {
      "filing_id": "usa:0000320193:0002100119-26-000139",
      "form": "13G",
      "filed": "2026-04-29",
      "accepted": "2026-04-29T16:40:10Z",
      "event_date": "2026-03-31",
      "filer_id": "usa:0002100119",
      "filer": "VANGUARD CAPITAL MANAGEMENT LLC",
      "holder_id": "usa:0002100119",
      "holder": "Vanguard Capital Management",
      "holder_type": "IA",
      "citizenship": "PA",
      "class_title": "Common Stock",
      "shares": "1099168953",
      "percent_of_class": "7.48",
      "sole_voting_power": "145321305",
      "shared_voting_power": "0",
      "sole_dispositive_power": "1099168953",
      "shared_dispositive_power": "0",
      "rule": "13d-1(b)",
      "issuer_address": "1 Apple Park Way, Cupertino, CA, 95014",
      "is_latest": true
    }
  ],
  "next_cursor": null
}

List the large stakes of a holder

GET /v1/investors/{cik}/beneficial-ownership

What one holder owns across companies, from its Schedules 13D and 13G. By default the current stake in each class of each company; history lists every filing. A page can hold fewer rows than limit and still end with a next_cursor: keep reading until it is null.

cik is the holder's CIK. company_id and company on each row name the company the stake is in. ticker keeps the stakes in one company, and a ticker that matches no company is 404 company_not_found.

A page can be shorter than limit. Keep following next_cursor until it is null.

MCP: tool filings_list_investor_beneficial_ownership.

Parameters

Response fields

curl -H "Authorization: Bearer $NARWHAL_API_KEY" \
  "https://api.narwhalapi.com/v1/investors/0000102909/beneficial-ownership?filed_lte=2025-10-31&limit=1"

{
  "id": "usa:0000102909",
  "holder": "The Vanguard Group",
  "stakes": [
    {
      "filing_id": "usa:0001770450:0000102909-25-000347",
      "form": "13G/A",
      "filed": "2025-10-31",
      "accepted": "2025-10-31T11:42:47Z",
      "event_date": "2025-09-30",
      "amendment_number": 8,
      "filer_id": "usa:0000102909",
      "filer": "VANGUARD GROUP INC",
      "holder_id": "usa:0000102909",
      "holder": "The Vanguard Group",
      "holder_type": "IA",
      "citizenship": "PA",
      "class_title": "Common Stock",
      "shares": "10397351",
      "percent_of_class": "8.26",
      "sole_voting_power": "0",
      "shared_voting_power": "733054",
      "sole_dispositive_power": "9549123",
      "shared_dispositive_power": "848228",
      "rule": "13d-1(b)",
      "issuer_address": "201 Merritt 7, Norwalk, CT, 06851",
      "is_latest": true,
      "company_id": "usa:0001770450",
      "company": "Xerox Holdings Corp"
    }
  ],
  "next_cursor": "eyJrIjoiNzk3NDg5Njg3OTc0…"
}

Search large-holder filers by name

GET /v1/beneficial-ownership/filers

Find a holder that files Schedules 13D or 13G by the start of its name. Returns the id to use as cik on the stakes route.

Returns the id to pass as cik on the stakes route. The name needs at least two letters or digits besides words like Inc, or the answer is 400 invalid_name.

MCP: tool filings_search_beneficial_ownership_filers.

Parameters

Response fields

curl -H "Authorization: Bearer $NARWHAL_API_KEY" \
  "https://api.narwhalapi.com/v1/beneficial-ownership/filers?name=vanguard&limit=3"

{
  "filers": [
    {
      "id": "usa:0002100119",
      "name": "VANGUARD CAPITAL MANAGEMENT LLC"
    },
    {
      "id": "usa:0001623658",
      "name": "Vanguard Charitable Endowment Program"
    },
    {
      "id": "usa:0002059874",
      "name": "Vanguard Development Holdings Limited"
    }
  ]
}

Search companies with large holders by name

GET /v1/beneficial-ownership/companies

Find a company that has Schedule 13D or 13G filings against it by the start of its name. Returns the id to use as company_id on the owners route.

Returns the id to pass as company_id on the owners route.

MCP: tool filings_search_beneficial_ownership_companies.

Parameters

Response fields

curl -H "Authorization: Bearer $NARWHAL_API_KEY" \
  "https://api.narwhalapi.com/v1/beneficial-ownership/companies?name=apple&limit=2"

{
  "companies": [
    {
      "id": "usa:0000320193",
      "name": "Apple Inc."
    },
    {
      "id": "usa:0001418121",
      "name": "Apple Hospitality REIT, Inc."
    }
  ]
}

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.