> ## 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.

# SEC 申报文件浏览

> 按 ticker 列出 SEC 10-K / 10-Q / 8-K 申报文件元数据 —— progressive disclosure 模式的第一步。

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

<Badge color="green" icon="circle-check">已上线</Badge>
 
<Badge color="gray" size="sm">免费 · listing</Badge>

## 它为 Agent 做什么

`sec_filing_browse` 是 SEC Filing **progressive disclosure 模式的第一步**：给定美股 ticker，返回该公司可用的 10-K / 10-Q / 8-K 元数据列表（不含正文）。agent 用它先发现公司有哪些 filing，再用 `sec_filing_read` 拉取具体章节内容 —— 10-K / 10-Q 用 `year` / `quarter`，8-K 用 `accession_number`（事件驱动，一年多份）。每份 filing 还会带上 `section_keys`（该 filing 可用的章节 code），agent 不读正文就能判断某份 8-K 讲的是什么。

Browse **不是 semantic search**：只接受 ticker + 可选 `filing_type`。不做关键词匹配，不做相关性排序，不接自然语言查询。

## 返回值

<ResponseField name="data" type="Filing[]" required>
  按 `filing_date` 倒序排列的申报文件数组。

  <Expandable title="Filing 字段">
    <ResponseField name="sec_filing_id" type="string" required>
      LLMQuant 稳定 filing id，跨请求一致。
    </ResponseField>

    <ResponseField name="ticker" type="string" required>
      股票代码（统一大写）。
    </ResponseField>

    <ResponseField name="company_name" type="string" nullable>
      SEC 提交时记录的公司名称。
    </ResponseField>

    <ResponseField name="filing_type" type="string" required>
      文件类型 —— `10-K`、`10-Q` 或 `8-K`。
    </ResponseField>

    <ResponseField name="accession_number" type="string" required>
      SEC 受理号（如 `0000320193-25-000079`）。**把它传给 `sec_filing_read` 可精确定位 filing。**
    </ResponseField>

    <ResponseField name="filing_date" type="string" required>
      向 SEC 提交的日期（`YYYY-MM-DD`）。
    </ResponseField>

    <ResponseField name="report_date" type="string" nullable>
      报告期截止日期（`YYYY-MM-DD`）。SEC 未提供时为 null。
    </ResponseField>

    <ResponseField name="url" type="string" required>
      SEC EDGAR 原文链接。
    </ResponseField>

    <ResponseField name="section_keys" type="string[]" required>
      这份 filing 可以读哪些章节 —— 如 8-K `["item2.02","item9.01","ex99.1"]`、10-K `["1","1A","7", …]`。空数组 `[]` 表示暂时还没有。把其中任意 code 传给 `sec_filing_read` 就能取那段。光看 code 也能判断 8-K 是什么：`item2.02` 是财报、`item5.02` 是高管变动，不用先打开看。
    </ResponseField>
  </Expandable>
</ResponseField>

<ResponseField name="meta.creditsUsed" type="number">固定 `0` —— browse 免费。</ResponseField>
<ResponseField name="meta.remainingCredits" type="number">账户剩余 credit。</ResponseField>

```json title="200 OK · sec_filing_browse" expandable theme={null}
{
  "data": [
    {
      "sec_filing_id": "a1b2c3d4-...",
      "ticker": "AAPL",
      "company_name": "Apple Inc.",
      "filing_type": "10-K",
      "accession_number": "0000320193-25-000079",
      "filing_date": "2025-10-31",
      "report_date": "2025-09-27",
      "url": "https://www.sec.gov/Archives/edgar/data/320193/000032019325000079/aapl-20250927.htm",
      "section_keys": ["1", "1A", "7", "7A", "8"]
    }
  ],
  "meta": { "creditsUsed": 0, "remainingCredits": 100 }
}
```

## 说明

<Tip>
  **两步检索是 canonical 模式**：`sec_filing_browse` 免费拉 filing 列表，再用 `sec_filing_read`（1 credit）抽取具体章节。把 browse 返回的 `accession_number` 直接传给 read，定位最干净。
</Tip>

<Tip>
  每份 filing 都带 `section_keys` —— 它可用的章节 code 列表。对一年多份、全叫「8-K」的 8-K，这是 agent 不读正文就挑对那份的关键：`item2.02` = earnings、`item5.02` = 高管变动、`ex99.1` = press release 附件。把想要的 code 直接传给 `sec_filing_read` 的 `items`。
</Tip>

<Tip>
  SEC filing 一旦公布就不会再变，结果可长期复用。某 ticker 的首次查询可能略慢，之后秒回。
</Tip>

<Warning>
  **支持 10-K、10-Q 和 8-K**。暂不支持 20-F、proxy（DEF 14A）等其他类型。
</Warning>

<Warning>
  **不支持日期范围过滤**（`filed_at_gte` / `filed_at_lte`），**不支持按 CIK 查询**。只接 `ticker`（+ 可选 `filing_type`）。
</Warning>

## 直接调用

<Accordion title="HTTP / SDK 示例" icon="terminal">
  <CodeGroup>
    ```typescript MCP (Claude / Cursor) theme={null}
    {
      "method": "tools/call",
      "params": {
        "name": "sec_filing_browse",
        "arguments": { "ticker": "AAPL", "filing_type": "10-K", "limit": 10 }
      }
    }
    ```

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

    resp = requests.get(
        "https://api.llmquantdata.com/api/filings",
        headers={"Authorization": f"Bearer {os.environ['LLMQUANT_API_KEY']}"},
        params={"ticker": "AAPL", "filing_type": "10-K", "limit": 10},
    ).json()
    for f in resp["data"]:
        print(f"{f['filing_type']}  {f['filing_date']}  {f['accession_number']}")
    ```

    ```bash cURL theme={null}
    curl "https://api.llmquantdata.com/api/filings?ticker=AAPL&filing_type=10-K&limit=10" \
      -H "Authorization: Bearer $LLMQUANT_API_KEY"
    ```
  </CodeGroup>
</Accordion>

## 完整参数参考

<Accordion title="sec_filing_browse — 请求参数" icon="sliders">
  <ParamField query="ticker" type="string" required>
    美股 ticker（如 `AAPL`、`MSFT`、`BRK.B`）。
  </ParamField>

  <ParamField query="filing_type" type="string">
    按文件类型过滤。可选值：`10-K`、`10-Q`、`8-K`。省略则全部返回。
  </ParamField>

  <ParamField query="limit" type="integer" default={10}>
    返回的最大 filing 数。默认 `10`，最大 `50`。
  </ParamField>
</Accordion>

## 相关接口

<Columns cols={3}>
  <Card title="SEC 申报文件章节读取" icon="file-lines" href="/zh-CN/api/filings/read">
    progressive disclosure 第二步 —— 从指定 filing 抽取具体 item 的完整文本。
  </Card>

  <Card title="13F 头部机构枚举" icon="ranking-star" href="/zh-CN/api/filings/13f-top-managers">
    枚举任意已覆盖季度的 Top 1000 机构集合，作为 consensus 分析的起点。
  </Card>

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