Build with a free SEC filings API使用免费 SEC 申报文件 API 构建数据流程

Choose the right free SEC filings API path选择合适的免费 SEC 申报文件 API 路径

A free SEC filings API search usually begins with price, but the decision is really about the answer shape and engineering responsibility. Official SEC sources provide authoritative submission metadata, filing documents, XBRL facts, and downloadable datasets. A third-party free tier may add ticker lookup, full-text or section search, normalized form-specific records, webhooks, bulk exports, or SDKs while imposing account, quota, retention, and licensing rules.

搜索免费 SEC 申报 API 往往从价格开始，但真正的选择取决于结果形态和工程责任。SEC 官方来源提供权威的提交元数据、申报文档、XBRL 事实和可下载数据集；第三方免费套餐可能增加股票代码查询、全文或章节搜索、表单专用标准化记录、webhook、批量导出或 SDK，同时带来账户、额度、保存和许可规则。

Define the job before choosing the endpoint. “Latest filings for a company” needs a submissions index; “revenue by quarter” needs XBRL facts plus taxonomy and period logic; “risk-factor text” needs document retrieval and section extraction; “insider purchase” or “institutional holding” needs ownership-form parsing; “new material event” needs form and item classification. One generic filings endpoint rarely solves all five correctly.

选择端点前，应先定义任务。“查询某公司最新申报”需要 submissions 索引；“按季度获取收入”需要 XBRL 事实、分类标准和期间逻辑；“提取风险因素”需要获取文档并解析章节；“内部人买入”或“机构持仓”需要解析所有权表单；“识别新的重大事件”则需要表单与项目分类。一个通用 filings 端点通常无法同时正确解决这五类问题。

What the official free SEC EDGAR API providesSEC EDGAR 官方免费 API 提供什么

The SEC EDGAR API documentation describes public JSON endpoints on data.sec.gov for submissions history and extracted XBRL data. These endpoints do not require an API key, but automated clients must identify themselves and follow current SEC access and security policies. Filing archives and primary documents live under SEC archive paths and should be linked by CIK, accession, and document name rather than treated as anonymous HTML pages.

SEC EDGAR API 官方文档说明了 data.sec.gov 上的公开 JSON 端点，包括申报历史与提取后的 XBRL 数据。这些端点无需 API 密钥，但自动化客户端必须标识自身并遵守 SEC 当前访问与安全政策。申报档案和主文档位于 SEC archive 路径中，应通过 CIK、申报编号和文档名建立关联，不能把它们当作没有身份的普通 HTML 页面。

Submissions JSON is a filing index, not the filing bodySubmissions JSON 是申报索引，不是申报正文

The company submissions response contains recent form types, filing and report dates, accession numbers, primary documents, and references to older submissions files. A complete backfill must follow those older-file references, handle amendments as separate filings, and preserve the sequence in which filings became public. The index tells you what exists; it does not contain every document, exhibit, inline XBRL fact, or narrative section.

公司 submissions 响应包含近期表单类型、提交与报告日期、申报编号、主文档，以及指向更早 submissions 文件的引用。完整回填必须继续读取这些历史文件引用，把修订作为独立申报处理，并保留文件公开的先后顺序。索引只能说明“有哪些申报”，并不包含所有文档、附件、内联 XBRL 事实或叙述章节。

XBRL endpoints answer fact-level questionsXBRL 端点用于事实级查询

Companyfacts, companyconcept, and frames expose machine-readable facts. They help with standardized metrics, but each fact still has taxonomy, unit, period, form, filed date, accession, and sometimes segment or dimensional context. Selecting “the latest value” without duration-versus-instant logic or amendment handling can mix incompatible facts. XBRL also does not replace narrative sections, exhibits, signatures, or ownership-form fields.

companyfacts、companyconcept 与 frames 提供机器可读事实，但每个事实仍带有分类标准、单位、期间、表单、提交日、申报编号，有时还包含分部或维度语境。如果不区分期间型与时点型事实，也不处理修订，直接选择“最新值”可能混入不可比数据。XBRL 同样不能替代叙述章节、附件、签名或所有权表单字段。

Model a source-linked SEC filing request设计保留来源的 SEC 申报请求模型

1. Resolve ticker to CIK1. 把股票代码解析为 CIK

CIK is the stable SEC entity identifier. Normalize it to the format required by the endpoint and store it alongside the ticker instead of treating ticker symbols as permanent identifiers.

CIK 是稳定的 SEC 实体标识。应按端点要求规范化 CIK，并与股票代码一起保存，不要把股票代码当作永久标识。

2. Filter by form and date2. 按表格与日期筛选

Separate filing date from report period, include amendments deliberately, and decide whether the application needs metadata, the primary HTML document, exhibits, or XBRL facts.

区分申报日期与报告期，明确是否纳入修订，并判断应用需要元数据、主 HTML 文档、附件还是 XBRL facts。

3. Preserve accession number and source URL3. 保留 accession number 与来源 URL

Store the raw response next to normalized fields. The accession number, form, filing date, CIK, retrieval time, and official SEC URL form the minimum useful provenance record.

将原始响应与标准化字段一起保存。accession number、表格类型、申报日期、CIK、获取时间和 SEC 官方 URL 构成最小可用来源记录。

4. Treat documents, exhibits, facts, and extracted sections as separate layers4. 把文档、附件、事实和提取章节分层保存

Store the filing index, raw primary document, exhibit inventory, structured facts, and derived section text independently. Each derived artifact should point to source accession, document, parser version, and extraction range. This prevents a parser update from silently changing the authoritative filing record.

申报索引、原始主文档、附件清单、结构化事实和派生章节文本应分别保存。每个派生产物都要指向来源申报编号、文档、解析器版本和提取范围，避免解析器升级时静默改变权威申报记录。

5. Build point-in-time versions, not one mutable “latest” row5. 建立时点化版本，而不是一条可变的“最新”记录

Keep original filings and amendments in filing-time order, then derive a current view and an as-known-at-time view. Research backtests should see only filings public by the analysis timestamp; production applications can separately expose the latest corrected state.

原始申报与修订应按照公开时间保留，再分别生成当前视图和“当时可知”视图。历史研究只能看到分析时点以前已经公开的文件；生产应用则可另行提供最新更正后的状态。

SEC filing clocks, processing states, and amendment historySEC 申报时间、处理状态与修订历史

A filing record needs more than one date. The report period describes the business period covered; the filing date is a calendar-level filing field; the SEC acceptance timestamp records when the submission entered EDGAR; retrieval time records when your system obtained it. A parsed fact can become available later than the raw document. Keep these clocks separate so an alert, backtest, and current dashboard can each use the correct one.

一条申报记录不能只有一个日期。报告期说明文件覆盖的经营期间；申报日是日历层面的提交字段；SEC 受理时间表示文件何时进入 EDGAR；抓取时间表示系统何时取得文件。结构化事实通常还会晚于原始文档完成解析。只有把这些时间分别保存，提醒、历史研究和当前看板才能使用各自正确的时点。

Compare free SEC filing data API limits比较免费 SEC 申报数据 API 的边界

Build a resilient SEC filings API Python client用 Python 构建可靠的 SEC 申报 API 客户端

Create one request layer that sets a descriptive User-Agent, timeout, and accepted response type. Add conservative pacing, conditional or immutable caching where appropriate, honor Retry-After, and retry temporary failures with jittered exponential backoff. Treat 403, 404, 429, and 5xx responses as different operational states rather than returning an empty dataset.

建立统一请求层，设置说明性 User-Agent、超时时间与预期响应格式。控制请求节奏，按资源性质使用条件缓存或不可变缓存，遵守 Retry-After，并对临时故障使用带随机抖动的指数退避。应分别处理 403、404、429 和 5xx，而不能一律返回空数据。

• Resolve and store CIK as a string, with effective-dated ticker mappings rather than a permanent ticker assumption.
• Ingest recent submissions and referenced older files, then reconcile accessions, forms, filing dates, report dates, and primary documents.
• Fetch and hash raw filing artifacts before parsing; keep parser and taxonomy versions with every derived record.
• Use bounded queues and global pacing across workers so parallel backfills still respect current access policy.
• Reconcile daily additions and amendments, and alert on unexplained accession disappearance, document changes, or parser row loss.
• Publish source URL, accession, form, filed date, report period, retrieval time, and derivation status with downstream answers.

• 把 CIK 以字符串保存，并使用带有效期的股票代码映射，不能假设 ticker 永久不变。
• 采集近期 submissions 和其引用的历史文件，再核对申报编号、表单、提交日、报告期和主文档。
• 解析前先获取并计算原始申报产物的哈希；每条派生记录都应带解析器与分类版本。
• 即使并行回填，也要通过有界队列和全局节奏控制遵守当前访问政策。
• 每日核对新增与修订，并对申报编号异常消失、文档变化或解析行丢失发出提醒。
• 下游回答应附带来源 URL、申报编号、表单、提交日、报告期、获取时间和派生状态。

Use QVeris to inspect SEC data capabilities使用 QVeris 检查 SEC 数据能力

QVeris helps developers and AI agents discover available capabilities before making a call. Open the QVeris tool details by job—submissions metadata, filing documents, company facts, filing sections, ownership records, or event alerts—then inspect CIK and ticker inputs, form and date filters, source evidence, historical coverage, amendments, pagination, derivation status, limits, and provider terms. The QVeris documentation explains the discovery and calling flow.

QVeris 帮助开发者和 AI Agent 在调用前发现可用能力。可在 QVeris 工具详情中按照任务搜索 submissions 元数据、申报文档、公司事实、申报章节、所有权记录或事件提醒，再检查 CIK 与 ticker 参数、表单与日期筛选、来源证据、历史覆盖、修订、分页、派生状态、限额和供应商条款。发现与调用流程请参考 QVeris 文档。

FAQ