SEC Filing API:
EDGAR JSON, Examples and ValidationSEC Filing API 实战指南：
EDGAR JSON、代码示例与数据验证

Decision brief

TL;DR

Who this guide is for and what you need适用对象与前置准备

This is for teams building filing research, risk-factor comparison, event monitoring, earnings preparation, financial extraction, or compliance assistants. It assumes a trusted backend, persistent storage, an HTML/XBRL parser, and a retrieval or citation layer.

适用于构建 Filing 研究、风险因素比较、事件监控、财报准备、财务抽取或合规助手的团队。默认你拥有可信后端、持久化存储、HTML/XBRL Parser 以及检索或引用层。

SEC EDGAR data sources: choose the right endpointSEC EDGAR 数据源：选择正确接口

Evidence-first filing agent architecture证据优先的 Filing Agent 架构

Keep acquisition, normalization, retrieval, and generation separate. The model should not invent URLs, accession numbers, dates, or units; those belong to deterministic services.

采集、标准化、检索和生成应分层。URL、Accession、日期与单位必须由确定性服务产生，而不是让模型猜测。

• Acquisition: polite HTTP client, cache, retry, conditional fetch, bulk downloads when appropriate.
• Raw evidence store: exact bytes, response headers, retrieval time, source URL, SHA-256 hash.
• Normalized filing record: CIK, accession, form, filing date, report date, primary document, amendment relationship.
• Document layer: cleaned sections, tables, exhibits, inline XBRL and character offsets back to source.
• Agent layer: retrieval filters, bounded context, citations, inference labels and refusal when evidence is insufficient.

• 采集层：礼貌 HTTP Client、缓存、重试、条件请求，并在适合时使用 Bulk Download。
• 原始证据库：原始字节、响应 Header、检索时间、Source URL 与 SHA-256 Hash。
• 标准化 Filing 记录：CIK、Accession、Form、Filing Date、Report Date、Primary Document 和 Amendment 关系。
• 文档层：清洗后的 Section、表格、Exhibit、Inline XBRL，以及返回源文档的字符位置。
• Agent 层：检索过滤、受控 Context、引用、推断标签，并在证据不足时拒绝作答。

Step 1: resolve ticker, company name, and CIK步骤一：解析 Ticker、公司名称与 CIK

EDGAR is organized around CIK, not ticker. Normalize the ticker, match it against the SEC mapping, confirm the legal entity name and exchange, and store the ten-digit zero-padded CIK for API requests. Never reuse a ticker mapping indefinitely: tickers and corporate identities can change.

EDGAR 以 CIK 而不是 Ticker 组织。先标准化 Ticker，与 SEC 映射匹配，核对 Legal Entity 与 Exchange，并保存补足 10 位的 CIK。不要永久复用映射，因为 Ticker 和公司身份可能变化。

import requests

HEADERS = {"User-Agent": "FilingAgent/1.0 research@example.com"}
rows = requests.get(
    "https://www.sec.gov/files/company_tickers.json",
    headers=HEADERS,
    timeout=20,
).json().values()

def resolve_ticker(symbol: str):
    symbol = symbol.upper().strip()
    row = next(x for x in rows if x["ticker"].upper() == symbol)
    return {
        "ticker": row["ticker"],
        "company": row["title"],
        "cik": str(row["cik_str"]).zfill(10),
    }

Step 2: query Submissions and select the filing步骤二：查询 Submissions 并选择 Filing

The recent filing arrays are columnar: values at the same index belong to one filing. Zip only known columns, filter by form and filing date, and retain both the filing date and report date. Include amendments deliberately instead of dropping every /A suffix.

近期 Filing 数组是列式结构：相同 Index 的值属于同一条 Filing。只 Zip 已知列，按 Form 与 Filing Date 过滤，同时保留 Filing Date 和 Report Date。Amendment 应显式处理，不要简单丢弃所有 /A。

def recent_filings(cik: str):
    url = f"https://data.sec.gov/submissions/CIK{cik}.json"
    payload = requests.get(url, headers=HEADERS, timeout=20).json()
    recent = payload["filings"]["recent"]
    keys = ["accessionNumber", "filingDate", "reportDate",
            "form", "primaryDocument", "primaryDocDescription"]
    return [dict(zip(keys, values)) for values in zip(*(recent[k] for k in keys))]

filing = next(
    f for f in recent_filings("0000320193")
    if f["form"] in {"10-K", "10-Q", "8-K"}
)

Step 3: reconstruct and preserve the filing document URL步骤三：重建并保存 Filing Document URL

An accession number identifies an accepted submission. Remove dashes only for the Archives directory, keep the original accession for citation, and combine it with the integer CIK and primary-document filename. Store the URL before parsing so every extracted passage can trace back to the exact document.

Accession Number 唯一标识一条已接受 Submission。只在 Archives 目录路径中移除横线，引用时保留原始 Accession，再与整数 CIK 和 Primary Document 文件名组合。解析前先保存 URL，确保每段抽取内容都能回到精确文档。

def filing_url(cik: str, filing: dict) -> str:
    cik_integer = str(int(cik))
    accession_path = filing["accessionNumber"].replace("-", "")
    document = filing["primaryDocument"]
    return (
        "https://www.sec.gov/Archives/edgar/data/"
        f"{cik_integer}/{accession_path}/{document}"
    )

source_url = filing_url("0000320193", filing)

Step 4: use XBRL facts without losing context步骤四：使用 XBRL Facts，但不丢失上下文

A numeric value is not meaningful by itself. Preserve taxonomy, concept, unit, start/end or instant date, fiscal year, fiscal period, form, filed date, accession, frame, and whether the fact was later repeated or amended. Prefer comparable standard-taxonomy facts, but fall back to the filing document for custom extensions and narrative context.

单独一个数值没有意义。必须保留 Taxonomy、Concept、Unit、Start/End 或 Instant Date、Fiscal Year、Fiscal Period、Form、Filed Date、Accession、Frame，以及该 Fact 是否后来被重复披露或修订。优先使用可比的标准 Taxonomy Fact；遇到自定义 Extension 与叙述上下文时回到 Filing 文档。

facts_url = "https://data.sec.gov/api/xbrl/companyfacts/CIK0000320193.json"
company_facts = requests.get(facts_url, headers=HEADERS, timeout=20).json()

revenue = company_facts["facts"]["us-gaap"]["RevenueFromContractWithCustomerExcludingAssessedTax"]
usd_facts = revenue["units"]["USD"]
annual = [x for x in usd_facts if x.get("form") == "10-K" and x.get("fp") == "FY"]

for fact in annual[-3:]:
    print(fact["val"], fact["fy"], fact["filed"], fact["accn"], fact.get("frame"))

End-to-end implementation pattern端到端实施模式

The production path should be deterministic until the evidence bundle is complete. Let the model choose a research intent or requested section, but keep identity resolution, filing selection, URL construction, parsing, hashing, and validation in code.

在证据包完成前，生产链路应保持确定性。模型可以判断研究意图或需要的 Section，但实体解析、Filing 选择、URL 构造、解析、Hash 与验证必须由代码完成。

Normalize one filing evidence contract统一 Filing Evidence Contract

{
  "entity": {"cik":"0000320193","ticker":"AAPL","name":"Apple Inc."},
  "filing": {
    "form":"10-K","accession":"0000320193-25-000079",
    "filed":"2025-10-31","report_date":"2025-09-27",
    "primary_document":"aapl-20250927.htm","source_url":"https://www.sec.gov/..."
  },
  "evidence": [{
    "section":"Risk Factors","text":"bounded extracted passage",
    "source_url":"https://www.sec.gov/...","document_sha256":"...",
    "retrieved_at":"2026-07-31T09:00:00Z"
  }],
  "answer_policy": {"cite_every_claim":true,"label_inference":true}
}

Keep the raw SEC field names in a source payload or provenance record even if your application uses normalized names. This makes audits and parser upgrades possible without re-downloading everything.

即使应用使用标准化字段名，也应在 Source Payload 或 Provenance Record 中保留 SEC 原始字段。这样才能审计和升级 Parser，而不必重新下载全部数据。

Validation checklist before the agent answersAgent 回答前的验证清单

Fair access, caching, cost, and latency controlsFair Access、缓存、成本与延迟控制

SEC guidance currently limits automated access to no more than ten requests per second in total and asks applications to identify themselves. Treat ten as a ceiling, not a target. Use a descriptive User-Agent, cache immutable filing documents, prefer bulk ZIP data for large backfills, use bounded concurrency, and implement exponential backoff for 403, 429, and transient 5xx responses.

SEC 当前指南把自动访问限制在总计不超过每秒 10 个请求，并要求应用声明身份。10 是上限，不是目标。使用可识别的 User-Agent；缓存不可变 Filing 文档；大规模回填优先使用 Bulk ZIP；限制并发；对 403、429 与临时 5xx 使用指数退避。

• Cache ticker mapping and Submissions responses briefly; cache accession documents by content hash for much longer.
• Poll filing metadata rather than repeatedly downloading the same full documents.
• Use nightly bulk archives for complete-history ingestion instead of millions of individual requests.
• Set connect/read timeouts, a retry budget, circuit breaking, and a dead-letter queue.
• Limit chunks, tables, exhibits, and XBRL facts sent to the model to control token cost and prompt-injection exposure.

• 短期缓存 Ticker Mapping 和 Submissions；按 Content Hash 长期缓存 Accession 文档。
• 轮询 Filing Metadata，不要反复下载相同完整文档。
• 完整历史回填使用每日 Bulk Archive，避免数百万次单独请求。
• 设置连接/读取超时、重试预算、熔断和 Dead-Letter Queue。
• 限制发送给模型的 Chunk、表格、Exhibit 与 XBRL Fact，控制 Token 成本和 Prompt Injection 暴露。

Common failure modes and troubleshooting常见失败模式与排错

How to evaluate a filing-aware AI agent如何评估 Filing-Aware AI Agent

Measure retrieval and evidence separately from writing quality. A fluent answer with the wrong accession or period is a failed answer.

检索与证据要和写作质量分开评估。即使语言流畅，只要 Accession 或期间错误，仍然是失败答案。

QVeris implementation pattern for filing researchQVeris Filing Research 实现模式

A QVeris-based agent can Discover filing or financial capabilities by intent, Inspect parameters and operational statistics, Probe candidate inputs and quote before execution, then Call the selected capability. Keep the SEC accession, source URL, filing dates, and extracted evidence in the application record; use SEC documents as the authoritative source for SEC filing claims.

基于 QVeris 的 Agent 可以按意图 Discover Filing 或金融能力，Inspect 参数与运维统计，在执行前 Probe 候选输入与报价，再 Call 选定能力。应用记录中仍应保存 SEC Accession、Source URL、Filing Date 与抽取证据；SEC 文档始终是 SEC Filing 结论的权威来源。

See the QVeris MCP documentation, SEC filings analysis agent guide, and SEC filing API comparison.

继续阅读 QVeris MCP 文档、SEC Filing Analysis Agent 指南与 SEC Filing API 对比。

FAQ

Official sources官方资料