瀏覽全部文件

機構持有人 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。

基礎網址: 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_idpath是字串公司 ID,例如 usa:0000320193。也接受股票代號別名,例如 usa:AAPL。
periodquery否日期報告季度的期末,例如 2026-06-30。省略則取最新季度。我們沒有資料的季度會得到 404 period_not_published。
cursorquery否字串上一頁的 next_cursor,其他參數須與上一頁相同。
limitquery否整數每頁資料列數。預設為 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。

參數

參數位置必填類型含義
cikpath是字串機構的 CIK,一到十位數字,或其 investor_id(usa: 加一到十位數字)。前導零可以省略。
periodquery否日期一個報告季度的期末。省略則取最新季度。不能與範圍參數一起使用。
report_period_gtequery否日期只取在這一天或之後結束的季度(YYYY-MM-DD)。
report_period_gtquery否日期只取在這一天之後結束的季度。
report_period_ltequery否日期只取在這一天或之前結束的季度。
report_period_ltquery否日期只取在這一天之前結束的季度。
cursorquery否字串上一頁的 next_cursor,其他參數須與上一頁相同。
limitquery否整數每頁資料列數。預設為 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。

參數

參數位置必填類型含義
namequery是字串機構名稱的一部分,不分大小寫,2 到 100 個字元。
cursorquery否字串上一頁的 next_cursor,其他參數須與上一頁相同。
limitquery否整數每頁資料列數。預設為 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。

參數

參數位置必填類型含義
cikpath是字串機構的 CIK,一到十位數字,或其 investor_id(usa: 加一到十位數字)。前導零可以省略。
report_period_gtequery否日期只取在這一天或之後結束的季度(YYYY-MM-DD)。
report_period_gtquery否日期只取在這一天之後結束的季度。
report_period_ltequery否日期只取在這一天或之前結束的季度。
report_period_ltquery否日期只取在這一天之前結束的季度。
formquery否字串只取這種表格的申報文件:13F-HR、13F-HR/A、13F-NT、13F-NT/A 或 13F-CTR。
cursorquery否字串上一頁的 next_cursor,其他參數須與上一頁相同。
limitquery否整數每頁資料列數。預設為 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…"
}

錯誤

錯誤使用共用的問題格式,並包含 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這個路由背後的申報文件目前無法讀取。請稍後再試。

此頁面對你有幫助嗎?