浏览全部文档

大股东 API 参考

来自 Schedule 13D 和 13G、持有公司超过 5% 股份的股东

概览

大股东是持有美国公司超过 5% 股份的个人和机构。他们在 Schedule 13D（适用于可能谋求控制权的股东，标记为 activist）和 Schedule 13G（适用于被动股东，标记为 passive）上申报，也在这两者的修订文件上申报。每个请求都需要 Bearer 密钥，REST 和 MCP 共用一份额度余额。

四个接口分别涵盖某一公司的大股东，某位股东在各公司的大额持股，以及两个用来查找要读取的股东或公司的名称搜索。公司用其 Filings API id 表示，例如 usa:0000320193。股东用其 CIK 表示。

默认情况下，接口返回当前持股：每位股东在每个股份类别中的最新申报文件。最新申报文件报告退出的持股，或同一申报人团体的后续申报文件已不再列出的持股，不会列出。发送 history=true 可读取每份申报文件，从新到旧排列。

历史从 2024 年 10 月的申报文件开始。某位股东的持股页的行数可能少于 limit，却仍带有 next_cursor，所以请继续读取，直到 next_cursor 为 null。只覆盖美国。

基础 URL： https://api.narwhalapi.com。 下面每个路由都是一个独立的 MCP 工具，参数相同。

高管、董事和持股 10% 以上者见 内部人交易页面。

公司 id 与 披露文件 API 公司搜索返回的 id 相同。

每个账户可获得的内容

查看所有账户
大股东，四个接口已包含

查看 价格 了解每次调用的费用。请求按其所属 API 的价格计费，除非某个路由另有说明。

  • 按公司价格计费。每次成功的响应计一次调用，无论返回多少行，空页同样计费。错误不计费。没有结果的搜索同样计费。
  • 数字为十进制字符串。没有值的字段省略，列表始终存在，像 officer 这样的标记只在为 true 时发送。
  • 联合申报中每位报告人一行，各行共用一个 filing_id。每个人在自己的封面上都写明同一个团体数字，所以切勿把同一份申报文件中各人的 shares 相加。请按 filing_id 对行分组，并从 group_total 读取团体的数字。
  • 申报文件未给出或无法清晰读取的数字会省略。不做任何估算。
  • 一个股东页最多读取 30 份公司文件，所以在数百家公司中有联合申报的股东，会返回较短的页，并以游标结尾。
  • 我们无法读取的少数申报文件不在答复之内。CUSIP 不属于任何答复。

端点

每个路由都是 GET 请求，并需要在以下请求头中携带你的密钥： Authorization: Bearer 标头。示例仅展示响应的结构，并非实时数据。

列出公司的大股东

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

持有公司超过 5% 股份的股东，来自 Schedule 13D 和 13G 及其修订文件。默认返回每位股东在每个类别中的当前持股；history 列出每份申报文件。

日期先缩小申报文件的范围，再选出每笔持股的最新一份，所以 filed_lte 给出的是公司在那一天的大股东情况。

MCP：工具 filings_list_beneficial_owners。

参数

参数位置必填类型含义
company_id路径参数是字符串公司 id，例如 usa:0000320193。也接受 usa:AAPL 这样的股票代码别名。
schedule查询参数否one of 13D, 13G仅限 13D（可能谋求控制权的股东）或 13G（被动股东）。
type查询参数否one of activist, passiveactivist 等同于 13D，passive 等同于 13G。同时发送 schedule 时，两者必须一致。
history查询参数否布尔值false（默认）返回当前持股。true 列出每份申报文件，从新到旧排列。
is_latest查询参数否布尔值仅在 history=true 时有效。true 保留每笔持股的最新申报文件，false 保留较早的申报文件。
filed查询参数否日期仅限在这一天提交的申报文件。
filed_from查询参数否日期与 filed_gte 相同。
filed_to查询参数否日期与 filed_lte 相同。
filed_gt查询参数否日期仅限在这一天之后提交的申报文件。
filed_gte查询参数否日期仅限在这一天或之后提交的申报文件。
filed_lt查询参数否日期仅限在这一天之前提交的申报文件。
filed_lte查询参数否日期仅限在这一天或之前提交的申报文件。
cursor查询参数否字符串上一页返回的 next_cursor，其他参数保持不变。
limit查询参数否整数每页行数。默认 50，最多 1000。

响应字段

字段类型传入含义
id字符串总是在所有人接口上是公司 id，在持股接口上是股东 id。
company字符串可选公司名称。
owners对象数组总是公司的大股东，从新到旧排列。
owners[].filing_id字符串总是该行所来自的申报文件的 id。
owners[].formone of 13D, 13D/A, 13G, 13G/A总是Schedule 的类型，以及它是否修订了较早的申报：13D、13D/A、13G 或 13G/A。
owners[].filed日期总是提交申报文件的日期。
owners[].accepted日期时间可选SEC 接受该申报文件的时刻。
owners[].event_date日期可选触发该申报的事件日期。
owners[].amendment_number整数可选修订的编号，申报文件注明时给出。
owners[].filer_id字符串可选申报文件第一位申报人的 id，即提交该文件的机构。
owners[].filer字符串可选第一位申报人的名称。可能与报告人不同。
owners[].holder_id字符串可选报告人的 id。个人没有。
owners[].holder字符串总是报告人的名称。
owners[].holder_type字符串可选该人的封面代码：IN 个人、CO 公司、PN 合伙企业、IA 投资顾问、HC 控股公司、BK 银行，另有其他。
owners[].citizenship字符串可选该人的国籍或组织所在地。
owners[].class_title字符串可选股份类别的名称。
owners[].shares字符串可选该人报告持有的股份。联合申报时不要把各人的数字相加，请使用 group_total。
owners[].percent_of_class字符串可选该人报告持有的占该类别的百分比。
owners[].sole_voting_power字符串可选该人单独拥有表决权的股份。
owners[].shared_voting_power字符串可选该人与他人共享表决权的股份。
owners[].sole_dispositive_power字符串可选该人单独拥有处分权的股份。
owners[].shared_dispositive_power字符串可选该人与他人共享处分权的股份。
owners[].group_boxone of a, b, ab可选该人在封面第 2 行勾选的项：a 是团体成员，b 不是团体成员或不确认，ab 两项都勾选。
owners[].rule字符串可选13G 所依据的规则：13d-1(b)、13d-1(c) 或 13d-1(d)。
owners[].funds字符串可选13D 的资金来源代码，例如 WC、AF、PF 或 OO。
owners[].typeone of activist, passive可选Schedule 13D 为 activist，Schedule 13G 为 passive。
owners[].legal_proceedings恒为 true可选封面上的法律程序方框被勾选时为 true。
owners[].excludes_certain_shares恒为 true可选封面上的排除某些股份的方框被勾选时为 true。
owners[].previously_filed恒为 true可选申报文件带有“此前已提交”标记时为 true。
owners[].issuer_address字符串可选公司的地址，按申报原文。
owners[].purpose字符串可选13D 的第 4 项，即交易目的。超过 4,000 个字符的部分截去。
owners[].items对象可选13D 的第 1、2、3、5 和 6 项，或 13G 的第 8 项的文本，各自超过 4,000 个字符的部分截去。仅包含申报文件给出的项。
owners[].joint整数可选申报文件列出的人数。
owners[].repeat恒为 true可选该人给出的数字，与申报文件中前面某人已给出的数字相同时为 true。
owners[].group_total字符串可选联合申报时，其中各人所报告的最大合计数。请在此读取团体的数字。
owners[].is_latest布尔值总是在请求所保留的申报文件中，该笔持股的最新一份申报文件上为 true。
owners[].exit恒为 true可选申报文件报告持股人持股在 5% 或以下、或没有股份时为 true。
owners[].superseded恒为 true可选同一申报人团体的后续申报文件不再列出的某笔持股，其最新一份申报文件上为 true。
next_cursor字符串总是将此值作为 cursor 传入以读取下一页。始终发送；最后一页为 null。
请求
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
}

列出某位股东的大额持股

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

某位股东在各公司的持有情况，来自其 Schedule 13D 和 13G。默认返回每家公司每个类别的当前持股；history 列出每份申报文件。一页的行数可能少于 limit，却仍带有 next_cursor：请继续读取，直到它为 null。

cik 是股东的 CIK。每行的 company_id 和 company 指出持股所在的公司。ticker 只保留某一家公司的持股，与任何公司都不匹配的股票代码返回 404 company_not_found。

一页的行数可能少于 limit。请持续沿用 next_cursor，直到它为 null。

MCP：工具 filings_list_investor_beneficial_ownership。

参数

参数位置必填类型含义
cik路径参数是字符串股东的 CIK，一到十位数字。
schedule查询参数否one of 13D, 13G仅限 13D（可能谋求控制权的股东）或 13G（被动股东）。
type查询参数否one of activist, passiveactivist 等同于 13D，passive 等同于 13G。同时发送 schedule 时，两者必须一致。
history查询参数否布尔值false（默认）返回当前持股。true 列出每份申报文件，从新到旧排列。
is_latest查询参数否布尔值仅在 history=true 时有效。true 保留每笔持股的最新申报文件，false 保留较早的申报文件。
filed查询参数否日期仅限在这一天提交的申报文件。
filed_from查询参数否日期与 filed_gte 相同。
filed_to查询参数否日期与 filed_lte 相同。
filed_gt查询参数否日期仅限在这一天之后提交的申报文件。
filed_gte查询参数否日期仅限在这一天或之后提交的申报文件。
filed_lt查询参数否日期仅限在这一天之前提交的申报文件。
filed_lte查询参数否日期仅限在这一天或之前提交的申报文件。
cursor查询参数否字符串上一页返回的 next_cursor，其他参数保持不变。
limit查询参数否整数每页行数。默认 50，最多 1000。
ticker查询参数否字符串仅限在此股票代码对应公司中的持股。

响应字段

字段类型传入含义
id字符串总是在所有人接口上是公司 id，在持股接口上是股东 id。
holder字符串可选股东的名称。
stakes对象数组总是该股东的持股，从新到旧排列。
stakes[].filing_id字符串总是该行所来自的申报文件的 id。
stakes[].formone of 13D, 13D/A, 13G, 13G/A总是Schedule 的类型，以及它是否修订了较早的申报：13D、13D/A、13G 或 13G/A。
stakes[].filed日期总是提交申报文件的日期。
stakes[].accepted日期时间可选SEC 接受该申报文件的时刻。
stakes[].event_date日期可选触发该申报的事件日期。
stakes[].amendment_number整数可选修订的编号，申报文件注明时给出。
stakes[].filer_id字符串可选申报文件第一位申报人的 id，即提交该文件的机构。
stakes[].filer字符串可选第一位申报人的名称。可能与报告人不同。
stakes[].holder_id字符串可选报告人的 id。个人没有。
stakes[].holder字符串总是报告人的名称。
stakes[].holder_type字符串可选该人的封面代码：IN 个人、CO 公司、PN 合伙企业、IA 投资顾问、HC 控股公司、BK 银行，另有其他。
stakes[].citizenship字符串可选该人的国籍或组织所在地。
stakes[].class_title字符串可选股份类别的名称。
stakes[].shares字符串可选该人报告持有的股份。联合申报时不要把各人的数字相加，请使用 group_total。
stakes[].percent_of_class字符串可选该人报告持有的占该类别的百分比。
stakes[].sole_voting_power字符串可选该人单独拥有表决权的股份。
stakes[].shared_voting_power字符串可选该人与他人共享表决权的股份。
stakes[].sole_dispositive_power字符串可选该人单独拥有处分权的股份。
stakes[].shared_dispositive_power字符串可选该人与他人共享处分权的股份。
stakes[].group_boxone of a, b, ab可选该人在封面第 2 行勾选的项：a 是团体成员，b 不是团体成员或不确认，ab 两项都勾选。
stakes[].rule字符串可选13G 所依据的规则：13d-1(b)、13d-1(c) 或 13d-1(d)。
stakes[].funds字符串可选13D 的资金来源代码，例如 WC、AF、PF 或 OO。
stakes[].typeone of activist, passive可选Schedule 13D 为 activist，Schedule 13G 为 passive。
stakes[].legal_proceedings恒为 true可选封面上的法律程序方框被勾选时为 true。
stakes[].excludes_certain_shares恒为 true可选封面上的排除某些股份的方框被勾选时为 true。
stakes[].previously_filed恒为 true可选申报文件带有“此前已提交”标记时为 true。
stakes[].issuer_address字符串可选公司的地址，按申报原文。
stakes[].purpose字符串可选13D 的第 4 项，即交易目的。超过 4,000 个字符的部分截去。
stakes[].items对象可选13D 的第 1、2、3、5 和 6 项，或 13G 的第 8 项的文本，各自超过 4,000 个字符的部分截去。仅包含申报文件给出的项。
stakes[].joint整数可选申报文件列出的人数。
stakes[].repeat恒为 true可选该人给出的数字，与申报文件中前面某人已给出的数字相同时为 true。
stakes[].group_total字符串可选联合申报时，其中各人所报告的最大合计数。请在此读取团体的数字。
stakes[].is_latest布尔值总是在请求所保留的申报文件中，该笔持股的最新一份申报文件上为 true。
stakes[].exit恒为 true可选申报文件报告持股人持股在 5% 或以下、或没有股份时为 true。
stakes[].superseded恒为 true可选同一申报人团体的后续申报文件不再列出的某笔持股，其最新一份申报文件上为 true。
stakes[].company_id字符串总是持股所在公司的 id。
stakes[].company字符串可选持股所在公司的名称。
next_cursor字符串总是将此值作为 cursor 传入以读取下一页。始终发送；最后一页为 null。
请求
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…"
}

按名称搜索大股东申报人

GET /v1/beneficial-ownership/filers

按名称开头查找申报 Schedule 13D 或 13G 的股东。返回 id，在持股接口上用作 cik。

返回 id，在持股接口上作为 cik 传入。名称中除 Inc 之类的词外，至少要有两个字母或数字，否则返回 400 invalid_name。

MCP：工具 filings_search_beneficial_ownership_filers。

参数

参数位置必填类型含义
name查询参数是字符串名称的开头字母。至少两个字母或数字。
country查询参数否字符串要搜索的登记机构所在国家的三字母代码。省略表示 USA。接口不覆盖的国家返回 404 not_covered。
limit查询参数否整数返回的结果数。默认 20，最多 100。

响应字段

字段类型传入含义
filers对象数组总是名称以该文本开头的申报人。
filers[].id字符串总是申报人的 id，在持股接口上作为 cik 传入。
filers[].name字符串总是申报人在申报文件中用过的名称。
请求
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"
    }
  ]
}

按名称搜索有大股东的公司

GET /v1/beneficial-ownership/companies

按名称开头查找有 Schedule 13D 或 13G 申报文件指向它的公司。返回 id，在所有人接口上用作 company_id。

返回 id，在所有人接口上作为 company_id 传入。

MCP：工具 filings_search_beneficial_ownership_companies。

参数

参数位置必填类型含义
name查询参数是字符串名称的开头字母。至少两个字母或数字。
country查询参数否字符串要搜索的登记机构所在国家的三字母代码。省略表示 USA。接口不覆盖的国家返回 404 not_covered。
limit查询参数否整数返回的结果数。默认 20，最多 100。

响应字段

字段类型传入含义
companies对象数组总是名称以该文本开头的公司。
companies[].id字符串总是公司的 id，在所有人接口上作为 company_id 传入。
companies[].name字符串总是公司名称。
请求
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."
    }
  ]
}

错误

错误使用通用的 problem 结构，并带有 request_id。查看 API 错误码与额度 了解该结构和额度相关的响应头。失败的请求不计费。

代码状态含义
invalid_query400参数缺失、未知、重复或超出范围。
invalid_cursor400该游标不是本请求返回的，或来自另一个请求。
invalid_name400去掉 Inc 之类的词后，名称不足两个字母或数字。
company_not_found404没有公司与该 id 匹配。
investor_not_found404没有 Schedule 13D 或 13G 申报人与该 CIK 匹配。
not_covered404尚未涵盖该市场、国家或公司。
insufficient_credits402您的额度余额低于该请求的费用。
company_data_unavailable503该接口背后的申报文件目前无法读取。请稍后重试。

此页面对你有帮助吗?