大額持股人 API 參考

持有公司股份超過 5% 的持有人，來自 Schedule 13D 和 13G

概覽

大額持股人是持有美國公司股份超過 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。僅涵蓋美國。

基礎網址： https://api.narwhalapi.com。下列每條路由都是各自獨立的 MCP 工具，參數相同。

高階主管、董事與持股 10% 以上的股東請見內部人交易頁面。

公司 ID 即為申報文件 API 公司搜尋所回傳的 ID。

每個帳戶都能取得的內容

費用	所有帳戶
大額持股人，四個路由	已包含

查看定價說明每次呼叫的費用。除非路由另有說明，請求依其所屬 API 的價格計費。

依 Companies 價格計費。每次成功回應計為一次呼叫，與資料列數無關，空白頁面也會計費。錯誤不計費。沒有符合結果的搜尋也會計費。
數字為十進位字串。沒有值的欄位會省略，清單一律存在，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`	path	是	字串	公司 ID，例如 `usa:0000320193`。也接受股票代號別名，例如 `usa:AAPL`。
`schedule`	query	否	one of 13D, 13G	僅限 `13D`（可能尋求控制權的持股人）或 `13G`（被動持股人）。
`type`	query	否	one of activist, passive	`activist` 等同於 `13D`，`passive` 等同於 `13G`。同時傳入 `schedule` 時，兩者必須一致。
`history`	query	否	布林值	`false`（預設）回傳目前的持股。`true` 列出每一份申報文件，由新到舊排列。
`is_latest`	query	否	布林值	僅限搭配 `history=true`。`true` 保留每筆持股的最新申報文件，`false` 保留較早的申報文件。
`filed`	query	否	日期	僅限在這一天提交的申報文件。
`filed_from`	query	否	日期	等同於 `filed_gte`。
`filed_to`	query	否	日期	等同於 `filed_lte`。
`filed_gt`	query	否	日期	僅限在這一天之後提交的申報文件。
`filed_gte`	query	否	日期	僅限在這一天或之後提交的申報文件。
`filed_lt`	query	否	日期	僅限在這一天之前提交的申報文件。
`filed_lte`	query	否	日期	僅限在這一天或之前提交的申報文件。
`cursor`	query	否	字串	上一頁的 `next_cursor`，其他參數須與上一頁相同。
`limit`	query	否	整數	每頁資料列數。預設為 50，最多 1000。

回應欄位

欄位	類型	傳送	含義
`id`	字串	固定回傳	在持有人路由上為公司 ID，在持股路由上為持股人 ID。
`company`	字串	選填	公司名稱。
`owners`	物件陣列	固定回傳	公司的大額持股人，由新到舊排列。
`owners[].filing_id`	字串	固定回傳	此資料列所屬申報文件的 ID。
`owners[].form`	one of 13D, 13D/A, 13G, 13G/A	固定回傳	附表的種類，以及是否修訂先前的附表：`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_box`	one 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[].type`	one 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 的 Item 4，即交易目的。截斷至 4,000 個字元。
`owners[].items`	對象	選填	13D 的 Item 1、2、3、5 和 6，或 13G 的 Item 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`	path	是	字串	持股人的 CIK，一至十位數字。
`schedule`	query	否	one of 13D, 13G	僅限 `13D`（可能尋求控制權的持股人）或 `13G`（被動持股人）。
`type`	query	否	one of activist, passive	`activist` 等同於 `13D`，`passive` 等同於 `13G`。同時傳入 `schedule` 時，兩者必須一致。
`history`	query	否	布林值	`false`（預設）回傳目前的持股。`true` 列出每一份申報文件，由新到舊排列。
`is_latest`	query	否	布林值	僅限搭配 `history=true`。`true` 保留每筆持股的最新申報文件，`false` 保留較早的申報文件。
`filed`	query	否	日期	僅限在這一天提交的申報文件。
`filed_from`	query	否	日期	等同於 `filed_gte`。
`filed_to`	query	否	日期	等同於 `filed_lte`。
`filed_gt`	query	否	日期	僅限在這一天之後提交的申報文件。
`filed_gte`	query	否	日期	僅限在這一天或之後提交的申報文件。
`filed_lt`	query	否	日期	僅限在這一天之前提交的申報文件。
`filed_lte`	query	否	日期	僅限在這一天或之前提交的申報文件。
`cursor`	query	否	字串	上一頁的 `next_cursor`，其他參數須與上一頁相同。
`limit`	query	否	整數	每頁資料列數。預設為 50，最多 1000。
`ticker`	query	否	字串	僅限持有此股票代號之公司的持股。

回應欄位

欄位	類型	傳送	含義
`id`	字串	固定回傳	在持有人路由上為公司 ID，在持股路由上為持股人 ID。
`holder`	字串	選填	持股人名稱。
`stakes`	物件陣列	固定回傳	持股人的持股，由新到舊排列。
`stakes[].filing_id`	字串	固定回傳	此資料列所屬申報文件的 ID。
`stakes[].form`	one of 13D, 13D/A, 13G, 13G/A	固定回傳	附表的種類，以及是否修訂先前的附表：`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_box`	one 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[].type`	one 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 的 Item 4，即交易目的。截斷至 4,000 個字元。
`stakes[].items`	對象	選填	13D 的 Item 1、2、3、5 和 6，或 13G 的 Item 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`	query	是	字串	名稱的前幾個字母。至少兩個字母或數字。
`country`	query	否	字串	要搜尋之登記機關的三字母國家代碼。省略表示美國。路由未涵蓋的國家回傳 404 not_covered。
`limit`	query	否	整數	要回傳的符合筆數。預設為 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`	query	是	字串	名稱的前幾個字母。至少兩個字母或數字。
`country`	query	否	字串	要搜尋之登記機關的三字母國家代碼。省略表示美國。路由未涵蓋的國家回傳 404 not_covered。
`limit`	query	否	整數	要回傳的符合筆數。預設為 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."
    }
  ]
}

錯誤

錯誤使用共用的問題格式，並包含 request_id。查看 API 錯誤處理：錯誤碼、額度與重試了解格式與額度標頭。失敗的請求不計費。

代碼	狀態	含義
`invalid_query`	400	參數缺漏、未知、重複，或超出範圍。
`invalid_cursor`	400	此游標不是這個請求所回傳的，或來自不同的請求。
`invalid_name`	400	去掉 Inc 這類詞之後，名稱不足兩個字母或數字。
`company_not_found`	404	沒有公司符合此 ID。
`investor_not_found`	404	沒有 Schedule 13D 或 13G 申報人符合此 CIK。
`not_covered`	404	尚未支援此市場、國家或公司。
`insufficient_credits`	402	您的額度餘額不足以支付此請求的費用。
`company_data_unavailable`	503	這個路由背後的申報文件目前無法讀取。請稍後再試。

此頁面對你有幫助嗎?