机构持有人 API 参考
持有某家公司的机构,以及每家机构的持仓,来自 Form 13F
概览
Form 13F 是管理资产至少 1 亿美元的机构投资管理人所持美国股票和期权持仓的季度报告。这些接口显示哪些机构持有某家公司,以及一家机构持有什么,每次一个报告季度。每个请求都需要 Bearer 密钥,REST 和 MCP 共用一份额度余额。
共有四个接口。第一个列出持有某家公司的机构。第二个列出一家机构的持仓。第三个按名称查找机构。第四个列出一家机构的 13F 申报文件,附上每份封面页上的数字。公司用其 Filings API 的 id 指定,例如 usa:0000320193。机构用它自己的 CIK 指定,其 investor_ 是 usa: 加上补足到十位的 CIK。
季度是报告季度的期末,例如 2026-06-30。省略则取最新季度。每一行是一个持仓,并写明季度及其所来自的申报文件。金额以美元计,不论申报文件使用什么单位。
历史数据从截至 2021 年 9 月 30 日的报告季度开始。periods 列出已保存的季度。列在此之前的季度只读取了一部分,所以其持有人数量不完整,也不是持有人的完整列表。
只覆盖美国。其他国家的公司返回 404 not_。
基础 URL: https:/。 下面每个路由都是一个独立的 MCP 工具,参数相同。
持股超过 5% 的股东见 大股东页面,内部人见 内部人交易页面。
公司 id 与 披露文件 API 公司搜索返回的 id 相同。
每个账户可获得的内容
| 查看 | 所有账户 |
|---|---|
| 公司的机构持有人 | 已包含 |
| 机构的持仓 | 已包含 |
| 名称搜索和申报文件列表 | 已包含 |
查看 价格 了解每次调用的费用。请求按其所属 API 的价格计费,除非某个路由另有说明。
- 按 Companies 价格计费,每 1,000 次调用 $10。每个成功的响应计一次调用,不论行数多少。空页、没有结果的搜索以及错误都免费。有行且带
next_的页面会计费,下一页如果为空则免费。cursor - 数字为十进制字符串。没有值的字段省略,列表始终存在,像
new_这样的标记只在为 true 时发送。position - 一页可能以
next_结尾。把它作为cursor cursor发回,其他参数保持不变。来自另一个请求的游标返回 400invalid_。cursor - 不带
period时,institutions 接口返回最新季度,同时也会列出最新报告属于更早季度的机构,并在其period中写明该季度。发送period则只读取一个季度。 reported_是申报文件所写的price value除以shares。它在 2023 年 1 月 3 日起提交的申报文件中发送,那时申报文件开始以美元表示金额;对本金和没有股数的持仓省略。更早的申报文件以千为单位表示金额,Narwhal 会以美元发送。shares_为type SH表示股份,PRN表示本金。期权持仓会发送put_。call other_是共同持有该持仓的其他纳入管理人的编号。他们的名称在 filings 接口的managers other_中。included_ managers shares_和change new_与机构的上一季度比较,由 holdings 接口发送。position table_是申报人在封面页上声明的数字。大约每 100 份申报文件中有 2 份是错的,所以如果需要真实数字,请自己数行数。entry_ total
端点
每个路由都是 GET 请求,并需要在以下请求头中携带你的密钥: Authorization: Bearer 标头。示例仅展示响应的结构,并非实时数据。
列出持有某家公司的机构
GET /v1/companies/{company_id}/institutions
在 Form 13F 上报告了某家公司持仓的机构,按价值从大到小排列。每一行是一家机构在一个报告季度的一个持仓。
行按价值从大到小排列。用 next_ 翻页即可读取每一家机构。
MCP:工具 filings_。
参数
| 参数 | 位置 | 必填 | 类型 | 含义 |
|---|---|---|---|---|
company_ | 路径参数 | 是 | 字符串 | 公司 id,例如 usa:0000320193。也接受 usa:AAPL 这样的股票代码别名。 |
period | 查询参数 | 否 | 日期 | 报告季度的期末,例如 2026-06-30。省略则取最新季度。我们没有数据的季度返回 404 period_。 |
cursor | 查询参数 | 否 | 字符串 | 上一页返回的 next_,其他参数保持不变。 |
limit | 查询参数 | 否 | 整数 | 每页行数。默认 100,最多 500。 |
响应字段
| 字段 | 类型 | 传入 | 含义 |
|---|---|---|---|
id | 字符串 | 总是 | 公司 id。 |
period | 日期 | 可选 | 所返回的报告季度的期末。向 holdings 接口请求季度范围时省略。 |
periods | list of date | 总是 | 已保存的报告季度的期末,从新到旧。 |
built_ | 字符串 | 可选 | 响应所依据的文件的构建时间(UTC)。 |
holders | 对象数组 | 总是 | 持有该公司的机构,按价值从大到小排列。 |
holders[].investor_ | 字符串 | 总是 | 机构的 id:usa: 加上补足到十位的 CIK。 |
holders[].investor | 字符串 | 可选 | 机构的名称,与其申报时一致。 |
holders[].filing_ | 字符串 | 总是 | 该行所来自的 13F 申报文件的 id。 |
holders[].form | 字符串 | 总是 | 申报文件的表格,例如 13F-HR。 |
holders[].report | always "combination" | 可选 | 申报文件是合并报告时为 combination:其中包含其他管理人的持仓。 |
holders[].amendment | one of restatement, new_holdings, unstated | 可选 | 修订对其所修改的申报文件所做的事:restatement、new_ 或 unstated。 |
holders[].filed | 日期 | 总是 | 提交申报文件的日期。 |
holders[].issuer | 字符串 | 总是 | 发行人的名称,与申报文件印出的一致。 |
holders[].class | 字符串 | 可选 | 证券类别的名称,例如 COM。 |
holders[].value | 字符串 | 总是 | 持仓的价值,以美元计。 |
holders[].shares | 字符串 | 总是 | 股数;当 shares_ 为 PRN 时是本金。 |
holders[].shares_ | one of SH, PRN | 可选 | SH 表示股份,PRN 表示本金。 |
holders[].put_ | one 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_ | 字符串 | 可选 | 该持仓价值占申报文件 table_ 的百分比。 |
holders[].reported_ | 字符串 | 可选 | 由 value 和 shares 算出的每股价格。见上面的限制说明。 |
holders[].other_ | list of string | 总是 | 共同持有该持仓的其他纳入管理人的编号。 |
holders[].percent_ | 字符串 | 可选 | 该持仓占公司已发行股份的百分比。仅限普通股份持仓。 |
holders[].outstanding_ | 日期 | 可选 | percent_ 所依据的股数的日期。 |
holders[].confidential_ | 恒为 true | 可选 | 申报人省略了向 SEC 申请保密处理的持仓时为 true。 |
next_ | 字符串 | 总是 | 将此值作为 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_、report_、report_ 和 report_ 可在一次调用中读取多个季度,最新季度在前,每个季度内按价值从大到小排列。此时不会发送 period。同时请求 period 和范围会返回 400 invalid_。
MCP:工具 filings_。
参数
| 参数 | 位置 | 必填 | 类型 | 含义 |
|---|---|---|---|---|
cik | 路径参数 | 是 | 字符串 | 机构的 CIK,一到十位数字,或其 investor_(usa: 加一到十位数字)。前导零可以省略。 |
period | 查询参数 | 否 | 日期 | 一个报告季度的期末。省略则取最新季度。不能与范围参数一起使用。 |
report_ | 查询参数 | 否 | 日期 | 只取在这一天或之后结束的季度(YYYY-MM-DD)。 |
report_ | 查询参数 | 否 | 日期 | 只取在这一天之后结束的季度。 |
report_ | 查询参数 | 否 | 日期 | 只取在这一天或之前结束的季度。 |
report_ | 查询参数 | 否 | 日期 | 只取在这一天之前结束的季度。 |
cursor | 查询参数 | 否 | 字符串 | 上一页返回的 next_,其他参数保持不变。 |
limit | 查询参数 | 否 | 整数 | 每页行数。默认 100,最多 500。 |
响应字段
| 字段 | 类型 | 传入 | 含义 |
|---|---|---|---|
id | 字符串 | 总是 | 机构的 id:usa: 加上补足到十位的 CIK。 |
investor | 字符串 | 可选 | 机构的名称,与其申报时一致。 |
period | 日期 | 可选 | 所返回的报告季度的期末。向 holdings 接口请求季度范围时省略。 |
periods | list of date | 总是 | 已保存的报告季度的期末,从新到旧。 |
built_ | 字符串 | 可选 | 响应所依据的文件的构建时间(UTC)。 |
holdings | 对象数组 | 总是 | 各持仓,按价值从大到小排列。请求季度范围时,最新季度在前。 |
holdings[].company_ | 字符串 | 可选 | 发行人在我们公司列表中的 id。发行人未匹配到公司时省略。 |
holdings[].company | 字符串 | 可选 | 发行人在我们公司列表中的名称。 |
holdings[].ticker | 字符串 | 可选 | 发行人在我们公司列表中的股票代码。 |
holdings[].filing_ | 字符串 | 总是 | 该行所来自的 13F 申报文件的 id。 |
holdings[].form | 字符串 | 总是 | 申报文件的表格,例如 13F-HR。 |
holdings[].report | always "combination" | 可选 | 申报文件是合并报告时为 combination:其中包含其他管理人的持仓。 |
holdings[].amendment | one of restatement, new_holdings, unstated | 可选 | 修订对其所修改的申报文件所做的事:restatement、new_ 或 unstated。 |
holdings[].filed | 日期 | 总是 | 提交申报文件的日期。 |
holdings[].issuer | 字符串 | 总是 | 发行人的名称,与申报文件印出的一致。 |
holdings[].class | 字符串 | 可选 | 证券类别的名称,例如 COM。 |
holdings[].value | 字符串 | 总是 | 持仓的价值,以美元计。 |
holdings[].shares | 字符串 | 总是 | 股数;当 shares_ 为 PRN 时是本金。 |
holdings[].shares_ | one of SH, PRN | 可选 | SH 表示股份,PRN 表示本金。 |
holdings[].put_ | one 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_ | 字符串 | 可选 | 该持仓价值占申报文件 table_ 的百分比。 |
holdings[].reported_ | 字符串 | 可选 | 由 value 和 shares 算出的每股价格。见上面的限制说明。 |
holdings[].other_ | list of string | 总是 | 共同持有该持仓的其他纳入管理人的编号。 |
holdings[].shares_ | 字符串 | 可选 | shares 相对于机构上一季度的变化。卖出时为负。 |
holdings[].new_ | 恒为 true | 可选 | 机构上一季度没有持有任何该股票时为 true。 |
holdings[].confidential_ | 恒为 true | 可选 | 申报人省略了向 SEC 申请保密处理的持仓时为 true。 |
next_ | 字符串 | 总是 | 将此值作为 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_,它可以直接作为其他接口上的 cik。
把 investor_,或只把其中的数字,作为 cik 传给其他接口。
MCP:工具 filings_。
参数
| 参数 | 位置 | 必填 | 类型 | 含义 |
|---|---|---|---|---|
name | 查询参数 | 是 | 字符串 | 机构名称的一部分,不分大小写,2 到 100 个字符。 |
cursor | 查询参数 | 否 | 字符串 | 上一页返回的 next_,其他参数保持不变。 |
limit | 查询参数 | 否 | 整数 | 每页行数。默认 100,最多 500。 |
响应字段
| 字段 | 类型 | 传入 | 含义 |
|---|---|---|---|
investors | 对象数组 | 总是 | 名称中含有该文本的机构。 |
investors[].investor_ | 字符串 | 总是 | 机构的 id:usa: 加上补足到十位的 CIK。 |
investors[].name | 字符串 | 总是 | 机构的名称,与其申报时一致。 |
investors[].latest_ | 日期 | 总是 | 该机构最新申报文件的报告季度期末。 |
next_ | 字符串 | 总是 | 将此值作为 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_。
参数
| 参数 | 位置 | 必填 | 类型 | 含义 |
|---|---|---|---|---|
cik | 路径参数 | 是 | 字符串 | 机构的 CIK,一到十位数字,或其 investor_(usa: 加一到十位数字)。前导零可以省略。 |
report_ | 查询参数 | 否 | 日期 | 只取在这一天或之后结束的季度(YYYY-MM-DD)。 |
report_ | 查询参数 | 否 | 日期 | 只取在这一天之后结束的季度。 |
report_ | 查询参数 | 否 | 日期 | 只取在这一天或之前结束的季度。 |
report_ | 查询参数 | 否 | 日期 | 只取在这一天之前结束的季度。 |
form | 查询参数 | 否 | 字符串 | 只取这种表格的申报文件:13F-HR、13F-HR/、13F-NT、13F-NT/ 或 13F-CTR。 |
cursor | 查询参数 | 否 | 字符串 | 上一页返回的 next_,其他参数保持不变。 |
limit | 查询参数 | 否 | 整数 | 每页行数。默认 100,最多 500。 |
响应字段
| 字段 | 类型 | 传入 | 含义 |
|---|---|---|---|
id | 字符串 | 总是 | 机构的 id:usa: 加上补足到十位的 CIK。 |
investor | 字符串 | 可选 | 机构的名称,与其申报时一致。 |
filings | 对象数组 | 总是 | 13F 申报文件,最新报告季度在前。 |
filings[].filing_ | 字符串 | 总是 | 该行所来自的 13F 申报文件的 id。 |
filings[].form | 字符串 | 总是 | 申报文件的表格,例如 13F-HR。 |
filings[].period | 日期 | 总是 | 该申报文件所涵盖的报告季度期末。 |
filings[].filed | 日期 | 总是 | 提交申报文件的日期。 |
filings[].report_ | 字符串 | 可选 | 封面页上印出的报告类型,例如 13F HOLDINGS REPORT。 |
filings[].amendment | one of restatement, new_holdings, unstated | 可选 | 修订对其所修改的申报文件所做的事:restatement、new_ 或 unstated。 |
filings[].amendment_ | 字符串 | 可选 | 封面页上印出的修订编号。 |
filings[].file_ | 字符串 | 可选 | 封面页上印出的 SEC 文件编号。 |
filings[].crd | 字符串 | 可选 | 封面页上印出的 CRD 编号。 |
filings[].table_ | 整数 | 可选 | 申报人在其表格中声明的条目数。 |
filings[].table_ | 字符串 | 可选 | 申报人为其表格声明的价值合计,以美元计。 |
filings[].other_ | 整数 | 可选 | 申报人声明了多少个其他纳入管理人。 |
filings[].other_ | 对象数组 | 总是 | 申报文件所包含持仓的其他管理人。 |
filings[].other_ | 整数 | 总是 | 管理人的编号。持仓的 other_ 指向它。 |
filings[].other_ | 字符串 | 可选 | 管理人的 id,当其自己提交 13F 时给出。 |
filings[].other_ | 字符串 | 可选 | 管理人的名称。 |
filings[].other_ | 字符串 | 可选 | 管理人的 SEC 文件编号。 |
filings[].other_ | 字符串 | 可选 | 管理人的 CRD 编号。 |
filings[].confidential_ | 恒为 true | 可选 | 申报人省略了向 SEC 申请保密处理的持仓时为 true。 |
filings[].notice | 恒为 true | 可选 | 通知类报告上为 true,它没有列出自己的持仓。 |
next_ | 字符串 | 总是 | 将此值作为 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_。查看 API 错误码与额度 了解该结构和额度相关的响应头。失败的请求不计费。
| 代码 | 状态 | 含义 |
|---|---|---|
invalid_ | 400 | 参数缺失、未知、重复或超出范围。 |
invalid_ | 400 | 该游标不是本请求返回的,或来自另一个请求。 |
company_ | 404 | 没有公司与该 id 匹配。 |
investor_ | 404 | 没有 13F 申报人与该 CIK 匹配。 |
period_ | 404 | 我们没有所问季度的 13F 数据。 |
not_ | 404 | 尚未涵盖该市场、国家或公司。 |
insufficient_ | 402 | 您的额度余额低于该请求的费用。 |
company_ | 503 | 该接口背后的申报文件目前无法读取。请稍后重试。 |
此页面对你有帮助吗?