Best SEC Filings APIs for AI Agents 面向 AI Agent 的最佳 SEC 文件 API

TL;DR: choose by workflow, not by logoTL;DR：按工作流选，不要按品牌选

Who this guide is for这份指南适合谁

This guide is for engineers building research copilots, event-monitoring agents, earnings workflows, compliance review, or retrieval systems that must answer with primary-source evidence. It assumes you can make HTTPS requests, store normalized JSON, and run a scheduled job or queue.

本文适合构建研究 Copilot、事件监控 Agent、财报工作流、合规审阅或检索系统的工程师，尤其是输出必须附带第一方证据的场景。你需要具备 HTTPS 请求、标准化 JSON 存储以及定时任务或队列的基础能力。

What an AI agent actually needs from a filing APIAI Agent 真正需要 Filing API 提供什么

“Returns a 10-K” is not a sufficient requirement. A production agent must identify the issuer, distinguish filing dates from reporting periods, preserve amendments, retrieve the primary document and exhibits, and prove which source supported every claim.

“能返回 10-K”并不是完整需求。生产级 Agent 必须确认发行人身份，区分提交日期与报告期，保留修订版本，获取主文件和附件，并证明每条结论来自哪份原始材料。

• Identity: CIK as the stable SEC key; ticker and legal name as aliases.身份：以 CIK 作为稳定 SEC 主键，Ticker 和法定名称作为别名。
• Discovery: filter by form, issuer, filing date, report date, and amendment status.发现：按表单、发行人、提交日期、报告期和修订状态过滤。
• Documents: primary HTML or text, filing index, exhibits, inline XBRL, and attachments.文档：主 HTML/TXT、Filing Index、附件、Inline XBRL 及其他提交材料。
• Evidence: accession number, canonical source URL, retrieval time, content hash, and cited section.证据：Accession Number、规范来源 URL、抓取时间、内容哈希和引用章节。
• Operations: documented limits, retries, caching, backfills, and predictable error behavior.运维：明确的限额、重试、缓存、历史回补和可预测的错误行为。

SEC filings APIs comparedSEC 文件 API 对比

Do not choose from a feature matrix alone. Run the same 25–50 filings through every shortlisted provider: recent and historical 10-Ks, 10-Qs, 8-Ks with exhibits, amendments, a renamed issuer, a ticker change, and at least one filing with custom taxonomy facts.

不要只看功能表。应把相同的 25–50 份文件交给每个候选供应商测试：近期与历史 10-K、10-Q、带附件的 8-K、修订文件、公司更名、Ticker 变更，以及至少一份含自定义 Taxonomy Fact 的文件。

Provider notes: where each option wins供应商详解：各自真正擅长什么

Reference architecture for a source-backed filing agent带来源证据的 Filing Agent 参考架构

Step-by-step: fetch the latest 10-K from EDGAR分步实现：从 EDGAR 获取最新 10-K

The SEC Submissions API is a good baseline because it forces the workflow to preserve first-party identifiers. Use a descriptive User-Agent with organization and contact information, cache responses, and stay below the SEC’s published fair-access ceiling.

SEC Submissions API 是很好的基线，因为它迫使工作流保留第一方标识。请使用包含组织与联系方式的可识别 User-Agent，缓存响应，并低于 SEC 公布的公平访问上限。

curl --compressed \
  -H "User-Agent: ResearchAgent/1.0 contact@example.com" \
  -H "Accept-Encoding: gzip, deflate" \
  "https://data.sec.gov/submissions/CIK0000320193.json"

import hashlib
import requests
from datetime import datetime, timezone

CIK = "0000320193"
HEADERS = {
    "User-Agent": "ResearchAgent/1.0 contact@example.com",
    "Accept-Encoding": "gzip, deflate",
}

submissions_url = f"https://data.sec.gov/submissions/CIK{CIK}.json"
data = requests.get(submissions_url, headers=HEADERS, timeout=30)
data.raise_for_status()
payload = data.json()
recent = payload["filings"]["recent"]

rows = [dict(zip(recent, values)) for values in zip(*recent.values())]
filing = next(row for row in rows if row["form"] == "10-K")

accession = filing["accessionNumber"]
accession_path = accession.replace("-", "")
cik_path = str(int(CIK))
primary = filing["primaryDocument"]
source_url = (
    f"https://www.sec.gov/Archives/edgar/data/"
    f"{cik_path}/{accession_path}/{primary}"
)

document = requests.get(source_url, headers=HEADERS, timeout=30)
document.raise_for_status()

evidence = {
    "cik": CIK,
    "accessionNumber": accession,
    "form": filing["form"],
    "filingDate": filing["filingDate"],
    "reportDate": filing["reportDate"],
    "primaryDocument": primary,
    "sourceUrl": source_url,
    "retrievedAt": datetime.now(timezone.utc).isoformat(),
    "sha256": hashlib.sha256(document.content).hexdigest(),
}

This example intentionally selects only the exact form 10-K. If your workflow should include amendments, model 10-K/A as a separate version and define how it affects earlier conclusions.

示例刻意只选择精确的 10-K。如果工作流需要包含修订文件，应将 10-K/A 建模为独立版本，并定义它如何影响此前结论。

Define an evidence contract before prompting the model在调用模型前先定义证据契约

Know which filing answers which question先明确不同 Filing 回答什么问题

Validation checklist before an agent can answerAgent 回答前的验证清单

• The CIK maps to the intended legal entity, not merely a matching ticker string.CIK 对应目标法定实体，而不只是匹配了 Ticker 字符串。
• The accession number has the expected format and resolves to a filing index or primary document.Accession Number 格式正确，并能解析到 Filing Index 或主文档。
• The form policy explicitly includes or excludes amendments.Form 策略明确包含或排除修订文件。
• Filing date, report date, acceptance time, and fiscal period are not conflated.提交日期、报告期、接收时间和财政期间没有混为一谈。
• Required exhibits were retrieved and linked to the parent filing.所需附件已经获取，并关联到父 Filing。
• XBRL facts agree on taxonomy, unit, duration or instant, dimensions, and period.XBRL Facts 的 Taxonomy、单位、时长或时点、维度和期间一致。
• Every generated claim has a source URL and exact evidence location.每条生成结论都有来源 URL 和精确证据位置。
• The stored hash and retrieval timestamp make the input reproducible.存储的哈希和抓取时间能让输入被复现。

Security, cost, and latency controls安全、成本与延迟控制

SEC currently asks automated users to make no more than 10 requests per second in total and may block excessive or unclassified bots. Treat that number as a ceiling, not a target. Use a shared rate limiter, descriptive User-Agent, cache, exponential backoff, jitter, and bulk archives for large backfills.

SEC 当前要求自动化用户总计不超过每秒 10 次请求，并可能阻止过量或无法识别的 Bot。应把这个数字当作上限而非目标。使用共享限流器、可识别 User-Agent、缓存、指数退避、抖动，并在大规模历史回补时使用 Bulk Archive。

Common failure modes and fixes常见失败模式与修复方式

News, transcripts, and prices are supporting layers—not filing APIs新闻、电话会与行情是辅助层，不是 Filing API

A news API explains market reaction. An earnings-call transcript adds management language. Price and volume data measure response. None of them replaces the filed document, accession number, amendment history, or SEC source URL. Retrieve the filing first, then join these datasets using issuer identity and event time.

新闻 API 用于解释市场反应，财报电话会文本补充管理层表达，价格与成交量用于衡量响应。但它们都不能替代已提交文件、Accession Number、修订历史或 SEC 来源 URL。应先获取 Filing，再按发行人身份和事件时间连接这些数据集。

QVeris implementation pattern: Discover → Inspect → CallQVeris 实现模式：Discover → Inspect → Call

In an agent system, QVeris can sit above provider-specific endpoints as a discovery and routing layer. The agent discovers candidate SEC tools, inspects the input schema and provider metadata, then calls the selected tool with bounded arguments. The returned evidence object should still name the underlying provider and retain the original SEC source.

在 Agent 系统中，QVeris 可以位于各供应商端点之上，承担发现与路由。Agent 先发现候选 SEC 工具，再检查输入 Schema 与供应商元数据，最后用受控参数调用所选工具。返回的证据对象仍应注明底层供应商，并保留原始 SEC 来源。

Frequently asked questions常见问题

Official sources and next steps官方资料与下一步

Provider features and access rules can change. Verify current documentation, entitlements, and terms before production use.

供应商功能与访问规则可能变化。生产使用前，请核对最新文档、权限和条款。