Best Earnings APIs for AI Agents 面向 AI Agent 的最佳财报 API

TL;DR: the best API depends on the earnings layerTL;DR：最佳 API 取决于你需要哪一层财报数据

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

This guide is for engineers building earnings monitors, portfolio-alert agents, research copilots, post-earnings summaries, estimate-revision screens, or event-driven trading research. It assumes you can store normalized JSON, schedule pre- and post-event jobs, and retain source records for review.

本文适合构建财报监控、组合提醒 Agent、研究 Copilot、财报后摘要、预期修订筛选或事件驱动研究的工程师。你需要能够存储标准化 JSON、安排事件前后任务，并保留可审阅的来源记录。

What “earnings data” actually includes“财报数据”到底包含哪些层

The word earnings often hides six different products. Treating them as one table causes date, period, and provenance errors.

Earnings 这个词往往掩盖了六种不同产品。把它们当成一张表，会产生日期、期间和来源错误。

Evaluation criteria for an agent-ready earnings APIAgent 可用的 Earnings API 选型指标

• Coverage: exchanges, countries, symbols, history depth, and delisted companies.覆盖：交易所、国家、Symbol、历史深度与退市公司。
• Event quality: predicted versus confirmed dates, before/after market labels, timezone, and reschedules.事件质量：预测/确认日期、盘前/盘后、时区与改期。
• Estimate quality: source methodology, analyst count, ranges, revisions, and as-of timestamps.预期质量：来源方法、分析师数量、区间、修订与 As-of 时间。
• Result semantics: GAAP versus adjusted EPS, diluted versus basic, revenue unit, and fiscal period.结果语义：GAAP/Adjusted EPS、Diluted/Basic、Revenue 单位与财政期间。
• Freshness: calendar refresh cadence, post-release latency, correction handling, and webhooks or polling.新鲜度：日历刷新频率、发布后延迟、修正处理以及 Webhook/轮询。
• Evidence: release, transcript, or filing URLs and enough metadata to reproduce an answer.证据：Release、Transcript 或 Filing URL，以及可复现答案的元数据。

Best earnings APIs compared最佳 Earnings API 对比

Run a representative bake-off. Include a confirmed event, a rescheduled event, a company with a non-calendar fiscal year, a negative EPS estimate, a zero estimate, an ADR, a dual listing, and a result later corrected by the provider.

用代表性样本实测。至少包含已确认事件、改期事件、非自然年公司、负 EPS 预期、零预期、ADR、双重上市，以及供应商后来修正的结果。

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

Reference architecture for an earnings analysis agent财报分析 Agent 参考架构

Step-by-step: build a normalized earnings event分步实现：构建标准化 Earnings Event

FMP's Stable API is a useful implementation example because calendar and symbol-level earnings use the same authentication pattern. Keep the API key in a server-side secret and query only the window your scheduler needs.

FMP Stable API 适合作为实现示例，因为 Calendar 与按 Symbol 的 Earnings 使用相同认证方式。API Key 应只保存在服务端，并只查询调度器需要的日期窗口。

curl --get "https://financialmodelingprep.com/stable/earnings-calendar" \
  --header "apikey: YOUR_API_KEY" \
  --data-urlencode "from=2026-07-27" \
  --data-urlencode "to=2026-07-31"

import hashlib
import json
import os
from datetime import datetime, timezone
from decimal import Decimal, InvalidOperation
import requests

BASE = "https://financialmodelingprep.com/stable"
HEADERS = {"apikey": os.environ["FMP_API_KEY"]}

response = requests.get(
    f"{BASE}/earnings-calendar",
    headers=HEADERS,
    params={"from": "2026-07-27", "to": "2026-07-31"},
    timeout=30,
)
response.raise_for_status()
records = response.json()

def number(value):
    if value is None or value == "":
        return None
    try:
        return Decimal(str(value))
    except InvalidOperation:
        return None

def surprise(actual, estimate):
    actual, estimate = number(actual), number(estimate)
    if actual is None or estimate is None or estimate == 0:
        return {"difference": None, "percent": None}
    return {
        "difference": str(actual - estimate),
        "percent": str((actual - estimate) / abs(estimate) * 100),
    }

normalized = []
for row in records:
    actual = row.get("epsActual")
    estimate = row.get("epsEstimated") or row.get("epsEstimate")
    raw = json.dumps(row, sort_keys=True, separators=(",", ":"))
    normalized.append({
        "symbol": row.get("symbol"),
        "reportDate": row.get("date"),
        "fiscalDateEnding": row.get("fiscalDateEnding"),
        "epsActual": actual,
        "epsEstimate": estimate,
        "revenueActual": row.get("revenueActual"),
        "revenueEstimate": row.get("revenueEstimated"),
        "surprise": surprise(actual, estimate),
        "provider": "financial-modeling-prep",
        "retrievedAt": datetime.now(timezone.utc).isoformat(),
        "rawSha256": hashlib.sha256(raw.encode()).hexdigest(),
        "raw": row,
    })

The fallback field names make the example resilient to common provider naming differences, but production code should validate the exact schema returned by your subscribed endpoint. Do not recompute a provider's published surprise percentage without documenting whether its denominator uses the estimate, absolute estimate, or another convention.

示例中的备用字段名用于适应常见命名差异，但生产代码仍应验证所订阅端点的准确 Schema。不要在未记录分母使用 Estimate、绝对值 Estimate 或其他规则的情况下，重新计算供应商发布的 Surprise 百分比。

Define the earnings evidence contract定义 Earnings 证据契约

Earnings surprise logic is more fragile than it looksEarnings Surprise 逻辑比看起来更脆弱

A beat or miss is meaningful only when actual and estimate share the same company, fiscal period, accounting basis, currency, unit, and estimate snapshot. Negative or zero EPS estimates make percentage surprise particularly easy to misread.

只有当 Actual 与 Estimate 具有相同公司、财政期间、会计口径、币种、单位和预期快照时，Beat/Miss 才有意义。负数或零 EPS Estimate 尤其容易让 Surprise 百分比被误读。

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

• The exchange-qualified symbol and issuer identity match the intended company.带交易所的 Symbol 与发行人身份匹配目标公司。
• Predicted, confirmed, rescheduled, and actual publication times remain separate versions.预测、确认、改期和实际发布时间保留为不同版本。
• Fiscal year, fiscal quarter, period end, and report date are not inferred from one another.财政年度、财政季度、Period End 和 Report Date 不互相推断。
• Actual and estimate use the same GAAP/adjusted and basic/diluted definition.Actual 与 Estimate 使用相同 GAAP/Adjusted 和 Basic/Diluted 定义。
• Revenue values share currency and scale, and null estimates do not become zero.Revenue 具有相同币种与数量级，空 Estimate 不被转换成零。
• The consensus snapshot includes provider, analyst count when available, and as-of time.Consensus 快照包含供应商、可用的分析师数量和 As-of 时间。
• Corrections create a new version and trigger re-evaluation of affected claims.修正生成新版本，并触发对受影响结论的重新评估。
• Material claims link to a release, transcript passage, or SEC filing—not only the normalized API row.重要结论链接到 Release、Transcript 段落或 SEC Filing，而不仅是标准化 API 行。

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

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

Transcripts and SEC filings are evidence layers—not substitutesTranscript 与 SEC Filing 是证据层，不是替代品

An earnings transcript explains management's narrative and analyst questions. An 8-K exhibit may contain the earnings release; a 10-Q or 10-K carries the filed financial statements and disclosures. Neither one supplies a time-stamped consensus estimate. The reliable pattern is to freeze the estimate, ingest the reported result, then attach narrative and primary evidence.

Earnings Transcript 解释管理层叙述与分析师问答；8-K 附件可能包含 Earnings Release；10-Q/10-K 提供已提交财务报表和披露。但它们都不提供带时间戳的 Consensus Estimate。可靠模式是先冻结预期，再采集实际结果，最后关联叙述与第一方证据。

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

QVeris can sit above provider-specific earnings endpoints as an agent-facing discovery and routing layer. The agent searches for the exact capability—calendar, estimates, actuals, surprise, transcript, or filing—inspects its schema and limits, then calls it with bounded inputs. The response must still preserve the underlying provider and evidence URLs.

QVeris 可以位于各供应商 Earnings 端点之上，承担面向 Agent 的发现与路由。Agent 搜索精确能力——Calendar、Estimates、Actuals、Surprise、Transcript 或 Filing——检查 Schema 与限额，再用受控输入调用。响应仍须保留底层供应商与证据 URL。

Frequently asked questions常见问题

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

API schemas, limits, plan entitlements, and update cycles can change. Verify the current official documentation and test representative symbols before production use.

API Schema、限额、套餐权限和更新周期可能变化。生产使用前，请核对当前官方文档并测试代表性 Symbol。