浏览全部文档

机构持有人 API 参考

持有某家公司的机构,以及每家机构的持仓,来自 Form 13F

概览

Form 13F 是管理资产至少 1 亿美元的机构投资管理人所持美国股票和期权持仓的季度报告。这些接口显示哪些机构持有某家公司,以及一家机构持有什么,每次一个报告季度。每个请求都需要 Bearer 密钥,REST 和 MCP 共用一份额度余额。

共有四个接口。第一个列出持有某家公司的机构。第二个列出一家机构的持仓。第三个按名称查找机构。第四个列出一家机构的 13F 申报文件,附上每份封面页上的数字。公司用其 Filings API 的 id 指定,例如 usa:0000320193。机构用它自己的 CIK 指定,其 investor_id 是 usa: 加上补足到十位的 CIK。

季度是报告季度的期末,例如 2026-06-30。省略则取最新季度。每一行是一个持仓,并写明季度及其所来自的申报文件。金额以美元计,不论申报文件使用什么单位。

历史数据从截至 2021 年 9 月 30 日的报告季度开始。periods 列出已保存的季度。列在此之前的季度只读取了一部分,所以其持有人数量不完整,也不是持有人的完整列表。

只覆盖美国。其他国家的公司返回 404 not_covered。

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

持股超过 5% 的股东见 大股东页面,内部人见 内部人交易页面。

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

每个账户可获得的内容

查看所有账户
公司的机构持有人已包含
机构的持仓已包含
名称搜索和申报文件列表已包含

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

  • 按 Companies 价格计费,每 1,000 次调用 $10。每个成功的响应计一次调用,不论行数多少。空页、没有结果的搜索以及错误都免费。有行且带 next_cursor 的页面会计费,下一页如果为空则免费。
  • 数字为十进制字符串。没有值的字段省略,列表始终存在,像 new_position 这样的标记只在为 true 时发送。
  • 一页可能以 next_cursor 结尾。把它作为 cursor 发回,其他参数保持不变。来自另一个请求的游标返回 400 invalid_cursor。
  • 不带 period 时,institutions 接口返回最新季度,同时也会列出最新报告属于更早季度的机构,并在其 period 中写明该季度。发送 period 则只读取一个季度。
  • reported_price 是申报文件所写的 value 除以 shares。它在 2023 年 1 月 3 日起提交的申报文件中发送,那时申报文件开始以美元表示金额;对本金和没有股数的持仓省略。更早的申报文件以千为单位表示金额,Narwhal 会以美元发送。
  • shares_type 为 SH 表示股份,PRN 表示本金。期权持仓会发送 put_call。
  • other_managers 是共同持有该持仓的其他纳入管理人的编号。他们的名称在 filings 接口的 other_included_managers 中。
  • shares_change 和 new_position 与机构的上一季度比较,由 holdings 接口发送。
  • table_entry_total 是申报人在封面页上声明的数字。大约每 100 份申报文件中有 2 份是错的,所以如果需要真实数字,请自己数行数。

端点

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

列出持有某家公司的机构

GET /v1/companies/{company_id}/institutions

在 Form 13F 上报告了某家公司持仓的机构,按价值从大到小排列。每一行是一家机构在一个报告季度的一个持仓。

行按价值从大到小排列。用 next_cursor 翻页即可读取每一家机构。

MCP:工具 filings_list_institutional_holders。

参数

参数位置必填类型含义
company_id路径参数是字符串公司 id,例如 usa:0000320193。也接受 usa:AAPL 这样的股票代码别名。
period查询参数否日期报告季度的期末,例如 2026-06-30。省略则取最新季度。我们没有数据的季度返回 404 period_not_published。
cursor查询参数否字符串上一页返回的 next_cursor,其他参数保持不变。
limit查询参数否整数每页行数。默认 100,最多 500。

响应字段

字段类型传入含义
id字符串总是公司 id。
period日期可选所返回的报告季度的期末。向 holdings 接口请求季度范围时省略。
periodslist of date总是已保存的报告季度的期末,从新到旧。
built_at字符串可选响应所依据的文件的构建时间(UTC)。
holders对象数组总是持有该公司的机构,按价值从大到小排列。
holders[].investor_id字符串总是机构的 id:usa: 加上补足到十位的 CIK。
holders[].investor字符串可选机构的名称,与其申报时一致。
holders[].filing_id字符串总是该行所来自的 13F 申报文件的 id。
holders[].form字符串总是申报文件的表格,例如 13F-HR。
holders[].reportalways "combination"可选申报文件是合并报告时为 combination:其中包含其他管理人的持仓。
holders[].amendmentone of restatement, new_holdings, unstated可选修订对其所修改的申报文件所做的事:restatement、new_holdings 或 unstated。
holders[].filed日期总是提交申报文件的日期。
holders[].issuer字符串总是发行人的名称,与申报文件印出的一致。
holders[].class字符串可选证券类别的名称,例如 COM。
holders[].value字符串总是持仓的价值,以美元计。
holders[].shares字符串总是股数;当 shares_type 为 PRN 时是本金。
holders[].shares_typeone of SH, PRN可选SH 表示股份,PRN 表示本金。
holders[].put_callone of Put, Call可选期权持仓上的 Put 或 Call。其他持仓省略。
holders[].discretion字符串可选申报文件所写的投资决定权:SOLE、DFND(共同,已界定)或 OTR(共同,其他)。
holders[].voting对象总是投票权,以股数计。
holders[].voting.sole字符串总是拥有单独投票权的股数。
holders[].voting.shared字符串总是拥有共同投票权的股数。
holders[].voting.none字符串总是没有投票权的股数。
holders[].period日期总是该持仓的报告季度期末。
holders[].percent_of_portfolio字符串可选该持仓价值占申报文件 table_value_total 的百分比。
holders[].reported_price字符串可选由 value 和 shares 算出的每股价格。见上面的限制说明。
holders[].other_managerslist of string总是共同持有该持仓的其他纳入管理人的编号。
holders[].percent_of_outstanding字符串可选该持仓占公司已发行股份的百分比。仅限普通股份持仓。
holders[].outstanding_as_of日期可选percent_of_outstanding 所依据的股数的日期。
holders[].confidential_omitted恒为 true可选申报人省略了向 SEC 申请保密处理的持仓时为 true。
next_cursor字符串总是将此值作为 cursor 传入以读取下一页。始终发送;最后一页为 null。
请求
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…"
}

列出一家机构的持仓

GET /v1/investors/{cik}/holdings

一家机构在 Form 13F 上所报告的内容,按价值从大到小排列,可取一个季度或一个季度范围。cik 是机构自己的 CIK。

report_period_gte、report_period_gt、report_period_lte 和 report_period_lt 可在一次调用中读取多个季度,最新季度在前,每个季度内按价值从大到小排列。此时不会发送 period。同时请求 period 和范围会返回 400 invalid_query。

MCP:工具 filings_list_investor_holdings。

参数

参数位置必填类型含义
cik路径参数是字符串机构的 CIK,一到十位数字,或其 investor_id(usa: 加一到十位数字)。前导零可以省略。
period查询参数否日期一个报告季度的期末。省略则取最新季度。不能与范围参数一起使用。
report_period_gte查询参数否日期只取在这一天或之后结束的季度(YYYY-MM-DD)。
report_period_gt查询参数否日期只取在这一天之后结束的季度。
report_period_lte查询参数否日期只取在这一天或之前结束的季度。
report_period_lt查询参数否日期只取在这一天之前结束的季度。
cursor查询参数否字符串上一页返回的 next_cursor,其他参数保持不变。
limit查询参数否整数每页行数。默认 100,最多 500。

响应字段

字段类型传入含义
id字符串总是机构的 id:usa: 加上补足到十位的 CIK。
investor字符串可选机构的名称,与其申报时一致。
period日期可选所返回的报告季度的期末。向 holdings 接口请求季度范围时省略。
periodslist of date总是已保存的报告季度的期末,从新到旧。
built_at字符串可选响应所依据的文件的构建时间(UTC)。
holdings对象数组总是各持仓,按价值从大到小排列。请求季度范围时,最新季度在前。
holdings[].company_id字符串可选发行人在我们公司列表中的 id。发行人未匹配到公司时省略。
holdings[].company字符串可选发行人在我们公司列表中的名称。
holdings[].ticker字符串可选发行人在我们公司列表中的股票代码。
holdings[].filing_id字符串总是该行所来自的 13F 申报文件的 id。
holdings[].form字符串总是申报文件的表格,例如 13F-HR。
holdings[].reportalways "combination"可选申报文件是合并报告时为 combination:其中包含其他管理人的持仓。
holdings[].amendmentone of restatement, new_holdings, unstated可选修订对其所修改的申报文件所做的事:restatement、new_holdings 或 unstated。
holdings[].filed日期总是提交申报文件的日期。
holdings[].issuer字符串总是发行人的名称,与申报文件印出的一致。
holdings[].class字符串可选证券类别的名称,例如 COM。
holdings[].value字符串总是持仓的价值,以美元计。
holdings[].shares字符串总是股数;当 shares_type 为 PRN 时是本金。
holdings[].shares_typeone of SH, PRN可选SH 表示股份,PRN 表示本金。
holdings[].put_callone of Put, Call可选期权持仓上的 Put 或 Call。其他持仓省略。
holdings[].discretion字符串可选申报文件所写的投资决定权:SOLE、DFND(共同,已界定)或 OTR(共同,其他)。
holdings[].voting对象总是投票权,以股数计。
holdings[].voting.sole字符串总是拥有单独投票权的股数。
holdings[].voting.shared字符串总是拥有共同投票权的股数。
holdings[].voting.none字符串总是没有投票权的股数。
holdings[].period日期总是该持仓的报告季度期末。
holdings[].percent_of_portfolio字符串可选该持仓价值占申报文件 table_value_total 的百分比。
holdings[].reported_price字符串可选由 value 和 shares 算出的每股价格。见上面的限制说明。
holdings[].other_managerslist of string总是共同持有该持仓的其他纳入管理人的编号。
holdings[].shares_change字符串可选shares 相对于机构上一季度的变化。卖出时为负。
holdings[].new_position恒为 true可选机构上一季度没有持有任何该股票时为 true。
holdings[].confidential_omitted恒为 true可选申报人省略了向 SEC 申请保密处理的持仓时为 true。
next_cursor字符串总是将此值作为 cursor 传入以读取下一页。始终发送;最后一页为 null。
请求
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…"
}

按名称搜索机构

GET /v1/investors

按名称的一部分查找提交 Form 13F 的机构。返回 investor_id,它可以直接作为其他接口上的 cik。

把 investor_id,或只把其中的数字,作为 cik 传给其他接口。

MCP:工具 filings_search_investors。

参数

参数位置必填类型含义
name查询参数是字符串机构名称的一部分,不分大小写,2 到 100 个字符。
cursor查询参数否字符串上一页返回的 next_cursor,其他参数保持不变。
limit查询参数否整数每页行数。默认 100,最多 500。

响应字段

字段类型传入含义
investors对象数组总是名称中含有该文本的机构。
investors[].investor_id字符串总是机构的 id:usa: 加上补足到十位的 CIK。
investors[].name字符串总是机构的名称,与其申报时一致。
investors[].latest_period日期总是该机构最新申报文件的报告季度期末。
next_cursor字符串总是将此值作为 cursor 传入以读取下一页。始终发送;最后一页为 null。
请求
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…"
}

列出一家机构的 13F 申报文件

GET /v1/investors/{cik}/filings

一家机构提交的每份 13F 申报文件的封面页,最新报告季度在前:表格、报告类型、申报日期、条目数、价值合计以及所含的其他管理人。

用 form 只保留一种表格,例如 13F-HR,再用范围参数保留部分季度。

MCP:工具 filings_list_investor_filings。

参数

参数位置必填类型含义
cik路径参数是字符串机构的 CIK,一到十位数字,或其 investor_id(usa: 加一到十位数字)。前导零可以省略。
report_period_gte查询参数否日期只取在这一天或之后结束的季度(YYYY-MM-DD)。
report_period_gt查询参数否日期只取在这一天之后结束的季度。
report_period_lte查询参数否日期只取在这一天或之前结束的季度。
report_period_lt查询参数否日期只取在这一天之前结束的季度。
form查询参数否字符串只取这种表格的申报文件:13F-HR、13F-HR/A、13F-NT、13F-NT/A 或 13F-CTR。
cursor查询参数否字符串上一页返回的 next_cursor,其他参数保持不变。
limit查询参数否整数每页行数。默认 100,最多 500。

响应字段

字段类型传入含义
id字符串总是机构的 id:usa: 加上补足到十位的 CIK。
investor字符串可选机构的名称,与其申报时一致。
filings对象数组总是13F 申报文件,最新报告季度在前。
filings[].filing_id字符串总是该行所来自的 13F 申报文件的 id。
filings[].form字符串总是申报文件的表格,例如 13F-HR。
filings[].period日期总是该申报文件所涵盖的报告季度期末。
filings[].filed日期总是提交申报文件的日期。
filings[].report_type字符串可选封面页上印出的报告类型,例如 13F HOLDINGS REPORT。
filings[].amendmentone of restatement, new_holdings, unstated可选修订对其所修改的申报文件所做的事:restatement、new_holdings 或 unstated。
filings[].amendment_no字符串可选封面页上印出的修订编号。
filings[].file_number字符串可选封面页上印出的 SEC 文件编号。
filings[].crd字符串可选封面页上印出的 CRD 编号。
filings[].table_entry_total整数可选申报人在其表格中声明的条目数。
filings[].table_value_total字符串可选申报人为其表格声明的价值合计,以美元计。
filings[].other_included_managers_count整数可选申报人声明了多少个其他纳入管理人。
filings[].other_included_managers对象数组总是申报文件所包含持仓的其他管理人。
filings[].other_included_managers[].sequence整数总是管理人的编号。持仓的 other_managers 指向它。
filings[].other_included_managers[].investor_id字符串可选管理人的 id,当其自己提交 13F 时给出。
filings[].other_included_managers[].name字符串可选管理人的名称。
filings[].other_included_managers[].file_number字符串可选管理人的 SEC 文件编号。
filings[].other_included_managers[].crd字符串可选管理人的 CRD 编号。
filings[].confidential_omitted恒为 true可选申报人省略了向 SEC 申请保密处理的持仓时为 true。
filings[].notice恒为 true可选通知类报告上为 true,它没有列出自己的持仓。
next_cursor字符串总是将此值作为 cursor 传入以读取下一页。始终发送;最后一页为 null。
请求
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…"
}

错误

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

代码状态含义
invalid_query400参数缺失、未知、重复或超出范围。
invalid_cursor400该游标不是本请求返回的,或来自另一个请求。
company_not_found404没有公司与该 id 匹配。
investor_not_found404没有 13F 申报人与该 CIK 匹配。
period_not_published404我们没有所问季度的 13F 数据。
not_covered404尚未涵盖该市场、国家或公司。
insufficient_credits402您的额度余额低于该请求的费用。
company_data_unavailable503该接口背后的申报文件目前无法读取。请稍后重试。

此页面对你有帮助吗?