Best Earnings APIs for AI Agents

TL;DR: the best API depends on the earnings layer

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.

What “earnings data” actually includes

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

Evaluation criteria for an agent-ready earnings API

• Coverage: exchanges, countries, symbols, history depth, and delisted companies.
• 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.
• Result semantics: GAAP versus adjusted EPS, diluted versus basic, revenue unit, and fiscal period.
• Freshness: calendar refresh cadence, post-release latency, correction handling, and webhooks or polling.
• Evidence: release, transcript, or filing URLs and enough metadata to reproduce an answer.

Best earnings APIs compared

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.

Provider notes: where each option wins

Reference architecture for an earnings analysis agent

Step-by-step: build a normalized 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.

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.

Define the earnings evidence contract

Earnings surprise logic is more fragile than it looks

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.

Validation checklist before the agent can answer

• The exchange-qualified symbol and issuer identity match the intended company.
• 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.
• Actual and estimate use the same GAAP/adjusted and basic/diluted definition.
• Revenue values share currency and scale, and null estimates do not become zero.
• The consensus snapshot includes provider, analyst count when available, and as-of time.
• 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.

Security, cost, and latency controls

Common failure modes and fixes

Transcripts and SEC filings are evidence layers—not substitutes

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.

QVeris implementation pattern: 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.

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.