機構持有人 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_。
基礎網址: 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_ | path | 是 | 字串 | 公司 ID,例如 usa:0000320193。也接受股票代號別名,例如 usa:AAPL。 |
period | query | 否 | 日期 | 報告季度的期末,例如 2026-06-30。省略則取最新季度。我們沒有資料的季度會得到 404 period_。 |
cursor | query | 否 | 字串 | 上一頁的 next_,其他參數須與上一頁相同。 |
limit | query | 否 | 整數 | 每頁資料列數。預設為 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 | path | 是 | 字串 | 機構的 CIK,一到十位數字,或其 investor_(usa: 加一到十位數字)。前導零可以省略。 |
period | query | 否 | 日期 | 一個報告季度的期末。省略則取最新季度。不能與範圍參數一起使用。 |
report_ | query | 否 | 日期 | 只取在這一天或之後結束的季度(YYYY-MM-DD)。 |
report_ | query | 否 | 日期 | 只取在這一天之後結束的季度。 |
report_ | query | 否 | 日期 | 只取在這一天或之前結束的季度。 |
report_ | query | 否 | 日期 | 只取在這一天之前結束的季度。 |
cursor | query | 否 | 字串 | 上一頁的 next_,其他參數須與上一頁相同。 |
limit | query | 否 | 整數 | 每頁資料列數。預設為 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 | query | 是 | 字串 | 機構名稱的一部分,不分大小寫,2 到 100 個字元。 |
cursor | query | 否 | 字串 | 上一頁的 next_,其他參數須與上一頁相同。 |
limit | query | 否 | 整數 | 每頁資料列數。預設為 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 | path | 是 | 字串 | 機構的 CIK,一到十位數字,或其 investor_(usa: 加一到十位數字)。前導零可以省略。 |
report_ | query | 否 | 日期 | 只取在這一天或之後結束的季度(YYYY-MM-DD)。 |
report_ | query | 否 | 日期 | 只取在這一天之後結束的季度。 |
report_ | query | 否 | 日期 | 只取在這一天或之前結束的季度。 |
report_ | query | 否 | 日期 | 只取在這一天之前結束的季度。 |
form | query | 否 | 字串 | 只取這種表格的申報文件:13F-HR、13F-HR/、13F-NT、13F-NT/ 或 13F-CTR。 |
cursor | query | 否 | 字串 | 上一頁的 next_,其他參數須與上一頁相同。 |
limit | query | 否 | 整數 | 每頁資料列數。預設為 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…"
}錯誤
錯誤使用共用的問題格式,並包含 request_。查看 API 錯誤 處理:錯誤碼、額度與重試 了解格式與額度標頭。失敗的請求不計費。
| 代碼 | 狀態 | 含義 |
|---|---|---|
invalid_ | 400 | 參數缺漏、未知、重複,或超出範圍。 |
invalid_ | 400 | 此游標不是這個請求所回傳的,或來自不同的請求。 |
company_ | 404 | 沒有公司符合此 ID。 |
investor_ | 404 | 沒有 13F 申報人與該 CIK 相符。 |
period_ | 404 | 我們沒有所問季度的 13F 資料。 |
not_ | 404 | 尚未支援此市場、國家或公司。 |
insufficient_ | 402 | 您的額度餘額不足以支付此請求的費用。 |
company_ | 503 | 這個路由背後的申報文件目前無法讀取。請稍後再試。 |
此頁面對你有幫助嗎?