> ## Documentation Index
> Fetch the complete documentation index at: https://docs.llmquantdata.com/llms.txt
> Use this file to discover all available pages before exploring further.

# 13F 按 Ticker 查持有人

> 反向查询 Top 1000 中持有某只美股的机构列表 —— 13F 反向查询。

<Note icon="sparkles">
  **已暴露为 MCP 工具**：`sec_13f_list_ticker_holders` —— 在 Claude / Cursor / 任意 MCP 客户端中直接调用。详见 [MCP Server](/zh-CN/integration/mcp-server) 60 秒配置。
</Note>

<Badge color="green" icon="circle-check">已上线</Badge>
 
<Badge color="blue" size="sm">每次 1 credit</Badge>

## 它做什么

查"谁持有某只美股"。传 ticker + 可选的 `year` + `quarter`，返回那一季 Top 1000 机构里持有这只票的列表 —— 每条带这家机构当季的持仓市值、股数，加上这家机构本身在 Top 1000 里的排名和规模。默认按持仓市值倒序。

`BRK.B` 这类带点的 ticker 服务端会自动改写成 `BRK-B`；查不到的 ticker 返回空列表（不是 404）。本工具是参数化查询，不是语义搜索。覆盖范围只到那一季的 Top 1000 机构（每个季度有各自的 Top 1000），**不是**全市场所有持有该股票的 13F 申报人 —— 长尾小机构、零售投资人都不在里面。

## 返回值

<ResponseField name="data" type="TickerHoldersResult" required>
  <Expandable title="TickerHoldersResult 字段">
    <ResponseField name="ticker" type="string" required>归一化后的 ticker（如 `BRK.B → BRK-B`）。</ResponseField>
    <ResponseField name="ranking_period" type="string" required>所对应的季末日期（`YYYY-MM-DD`），= 你传入的 (year, quarter) 对应季末。</ResponseField>

    <ResponseField name="total_holders_in_scope" type="integer" required>
      Top 1000 内持有该 ticker 的机构数（≤ 1000）。用它判断 cohort 规模再决定下一步。
    </ResponseField>

    <ResponseField name="aggregate_value_usd" type="number" required>
      所有 in-scope 持有人的 `value_usd` 之和。
    </ResponseField>

    <ResponseField name="holders" type="HolderEntry[]" required>
      默认按 `value_usd` 倒序。

      <Expandable title="HolderEntry 字段">
        <ResponseField name="manager_cik" type="string" required>持有人 CIK。</ResponseField>
        <ResponseField name="manager_name" type="string" required>规范化的机构名称。</ResponseField>
        <ResponseField name="manager_period_reportable_value_usd" type="number" nullable>该 manager 在 `ranking_period` 这季的 13F reportable value（AUM proxy）。**该季排名数据暂不可用时为 null** —— 持仓仍会返回，只是缺这一项排名数值。</ResponseField>
        <ResponseField name="manager_period_of_report" type="string" nullable>上一字段对应的季度；ranking 缺失时为 null。</ResponseField>
        <ResponseField name="manager_period_rank" type="integer" nullable>该 manager 在 `ranking_period` 这季的 Top 1000 排名；ranking 缺失时为 null。</ResponseField>
        <ResponseField name="accession_number" type="string" required>SEC 受理号。</ResponseField>
        <ResponseField name="cusip" type="string" required>持仓 CUSIP。</ResponseField>
        <ResponseField name="title_of_class" type="string" required>证券类别。</ResponseField>
        <ResponseField name="value_usd" type="number" required>持仓市值（USD）。</ResponseField>
        <ResponseField name="shares" type="number" required>股数。</ResponseField>
        <ResponseField name="shares_type" type="string" required>`SH` 或 `PRN`。</ResponseField>
      </Expandable>
    </ResponseField>
  </Expandable>
</ResponseField>

<ResponseField name="meta.creditsUsed" type="number">本次调用消耗的 credit（固定 `1`）。</ResponseField>
<ResponseField name="meta.remainingCredits" type="number">本次调用后的剩余 credits。</ResponseField>
<ResponseField name="meta.notice" type="string">需要说明覆盖范围或空结果时返回的人话说明。</ResponseField>

```json title="200 OK · sec_13f_list_ticker_holders" expandable theme={null}
{
  "data": {
    "ticker": "NVDA",
    "ranking_period": "2025-12-31",
    "total_holders_in_scope": 187,
    "aggregate_value_usd": 123456789000,
    "holders": [
      {
        "manager_cik": "1067983",
        "manager_name": "BERKSHIRE HATHAWAY INC",
        "manager_period_reportable_value_usd": 302459211458,
        "manager_period_of_report": "2025-12-31",
        "manager_period_rank": 7,
        "accession_number": "0000950123-26-001234",
        "cusip": "67066G104",
        "title_of_class": "COM",
        "value_usd": 1234567890,
        "shares": 9000000,
        "shares_type": "SH"
      }
    ]
  },
  "meta": {
    "creditsUsed": 1,
    "remainingCredits": 999,
    "notice": "Holders list is restricted to the Top 1,000 manager set; not full-market ownership. 13F coverage: Top 1,000 managers for quarter 2025-12-31 (each quarter has its own Top 1,000). Ranking data available for 4 quarters: 2025-03-31 … 2025-12-31. Reportable value is an AUM proxy excluding fixed income, options, non-U.S. holdings, and shorts."
  }
}
```

## 说明

<Tip>
  **canonical 工作流**：本反向查询与 `sec_13f_list_top_managers`（确定 covered manager set 规模）以及 `sec_13f_list_manager_holdings`（钻进单只基金的全部持仓）配合使用。本工具回答 "谁持有 X？"，正向工具回答 "这只基金在持什么？"。
</Tip>

<Tip>
  用 `manager_period_rank` 和 `manager_period_reportable_value_usd` 在客户端做过滤 —— 比如只展示持有人中 Top 30 的机构，避免大量长尾小持仓干扰。
</Tip>

<Tip>
  **典型 agent 问法**：本工具只返回单季持有人名单，跨季度变化需要 agent 自己调两次再对比。

  <Prompt description="某 ticker 的某季持有人">
    最近一季 13F 里，NVDA 在 smart money 中有哪些机构持仓？按市值前 20 列出来。
  </Prompt>

  <Prompt description="同 ticker 跨季度持有人变化">
    NVDA 这两季的 smart money 持有人对比一下，谁新进的？谁退出的？谁加仓最多？
  </Prompt>

  注意覆盖范围仅那一季的 Top 1000 covered manager set，不是全市场持有人；某机构两季的可见性差异也可能来自"它本季掉出那季的 Top 1000"而不是真的"退出该股"，agent 解读时要小心。
</Tip>

<Warning>
  **仅 Top 1000 机构 scope**，**不是**全市场持有人。那一季 covered manager set 之外的基金（以及零售 / 直接持有人）不在结果里。
</Warning>

<Warning>
  如果被查季度的 Top 1000 里没有机构持有该 ticker，工具返回 `200 OK` + 空 `holders` + `meta.notice`。
</Warning>

<Warning>
  暂不支持 confidential / 延迟披露持仓。
</Warning>

## 直接调用

<Accordion title="HTTP / SDK 示例" icon="terminal">
  <CodeGroup>
    ```typescript MCP (Claude / Cursor) theme={null}
    {
      "method": "tools/call",
      "params": {
        "name": "sec_13f_list_ticker_holders",
        "arguments": { "ticker": "NVDA", "year": 2025, "quarter": 4, "limit": 100 }
      }
    }
    ```

    ```python Python (HTTP) theme={null}
    import os, requests

    resp = requests.get(
        "https://api.llmquantdata.com/api/filings/13f/by-ticker",
        headers={"Authorization": f"Bearer {os.environ['LLMQUANT_API_KEY']}"},
        params={"ticker": "NVDA", "year": 2025, "quarter": 4, "limit": 50},
    ).json()
    data = resp["data"]
    print(f"{data['ticker']} {data['ranking_period']}: {data['total_holders_in_scope']} holders")
    for h in data["holders"][:10]:
        print(f"  #{h['manager_period_rank']:>4}  {h['manager_name']:<40}  ${h['value_usd']:>15,}")
    ```

    ```bash cURL theme={null}
    curl "https://api.llmquantdata.com/api/filings/13f/by-ticker?ticker=NVDA&year=2025&quarter=4&limit=50" \
      -H "Authorization: Bearer $LLMQUANT_API_KEY"
    ```
  </CodeGroup>
</Accordion>

## 完整参数参考

<Accordion title="sec_13f_list_ticker_holders — 请求参数" icon="sliders">
  <ParamField query="ticker" type="string" required>
    美股 ticker（如 `NVDA`、`TSLA`、`AAPL`）。大小写不敏感，服务端自动归一化（`BRK.B → BRK-B`）。
  </ParamField>

  <ParamField query="year" type="integer">
    要查询的季度所在年（如 `2025`）。范围 `[2013, 2030]`。**必须与 `quarter` 同传或同省**；省略则默认 = 最新已覆盖季度。
  </ParamField>

  <ParamField query="quarter" type="integer">
    要查询的季度 `1-4`（Q1=Jan-Mar，Q4=Oct-Dec）。**必须与 `year` 同传或同省**。
  </ParamField>

  <ParamField query="limit" type="integer" default={100}>
    最多返回的持有人数。默认 `100`，最大 `1000` —— 如需 Top 1000 全量再客户端按 manager AUM proxy 裁剪，可调到上限。
  </ParamField>
</Accordion>

## 相关接口

<Columns cols={3}>
  <Card title="13F 按机构查持仓" icon="briefcase" href="/zh-CN/api/filings/13f-by-manager">
    正向方向 —— 列出某只基金某季度的全部持仓。
  </Card>

  <Card title="13F 头部机构枚举" icon="ranking-star" href="/zh-CN/api/filings/13f-top-managers">
    枚举覆盖的 Top 1000 机构集合，给持有人 cohort 定大小或做过滤。
  </Card>

  <Card title="MCP Server 接入" icon="plug" href="/zh-CN/integration/mcp-server">
    60 秒接入 Claude / Cursor / 任意 agent harness。
  </Card>
</Columns>