Build with a Free Earnings Data API
Compare the fields, timing, limits, and checks needed for dependable earnings workflows.
TL;DR
A historical earnings data API should preserve a point-in-time record of reported results, analyst-consensus snapshots, surprise calculations, release times, and later revisions across many companies and quarters. Its main value is a reproducible research panel for event studies, screening, and model features—not only a feed of the latest result. A dataset that keeps only today's consensus or latest corrected EPS cannot reproduce what investors knew before an older announcement.
A free earnings data API can power calendars, alerts, screening, research notes, and event-driven agent workflows.
Require a stable symbol, fiscal period, report date, reported EPS, estimated EPS, currency, and update timestamp.
Fields a useful earnings API should return
The keyword sounds simple, but a research-grade dataset needs more than one row per quarter. Separate company and security identity, fiscal period, scheduled event, actual release, reported result, every eligible estimate snapshot, provider ingestion time, and revision version. This prevents a calendar date from being mistaken for publication time and a post-release estimate from leaking into a historical surprise calculation.
Capture legal company ID, security and exchange, fiscal year, fiscal quarter, period end, and event ID. Preserve ticker and fiscal-calendar changes with effective dates instead of treating them as new companies.
Keep the scheduled date, confirmation status, expected session, actual release timestamp, timezone, source timestamp, and provider ingestion time separately. Historical studies should use the instant results became public.
Store reported and adjusted EPS, revenue, and other target metrics with currency, GAAP or IFRS basis, basic or diluted label, continuing-operations scope, and source. Do not collapse company-adjusted and reported values into one field.
Retain estimate value, observation time, contributor count, dispersion, high and low range, and methodology for every required cutoff. The pre-release snapshot and the latest snapshot answer different questions.
Save actual and estimate components with absolute and percentage surprise, a near-zero denominator flag, revision history, and the market session used for any return window. Derived fields need formulas and version IDs.
For a representative earnings season, compare the company's release, regulatory filing, and API response for the same metric and period. Record whether differences come from GAAP versus adjusted presentation, continuing operations, currency conversion, share basis, rounding, or a later correction. Define which source wins for each field instead of silently accepting the newest number.
Worked reconciliation example: compare like with like
Assume a company release reports GAAP diluted EPS of $0.80 and company-adjusted diluted EPS of $1.05 for the same quarter. The final pre-release consensus snapshot is $1.00, and its methodology says “adjusted diluted EPS.” The valid surprise comparison is therefore ($1.05 − $1.00) ÷ $1.00 = +5%. Comparing GAAP actual EPS of $0.80 with that adjusted consensus would produce ($0.80 − $1.00) ÷ $1.00 = −20% and reverse the direction of the conclusion even though every individual number is genuine.
Store the two actuals as separate facts, link each to the release table and later filing, and label the estimate’s accounting basis, share basis, contributor count, and observation cutoff. Keep the issuer’s reconciliation from GAAP to adjusted earnings as evidence rather than deriving an undocumented adjustment locally. If the API cannot establish that actual and estimate use compatible definitions, return the raw values with a comparability warning and leave percentage surprise unset. A later provider correction should append a new version and identify which derived results must be recalculated; it should not silently overwrite the historical record used by an earlier study.
Which free earnings data source should you start with?
The best starting point depends on whether the application needs authoritative reported facts, a ready-made earnings calendar, analyst estimates, or all three. These sources are complementary rather than interchangeable. A regulator can establish what the company filed, but it does not provide a precomputed analyst consensus; a convenient market-data endpoint can supply estimates and surprise fields, but those values still need a documented cutoff and a reconciliation path back to the company release or filing.
| Starting point | What it provides | Best fit | What remains unresolved |
|---|---|---|---|
| SEC EDGAR | Public filing history and extracted XBRL facts without an API key; submissions and XBRL data are updated as filings are disseminated. | Authoritative US issuer facts, filing timestamps, and reconciliation. | No ready-made analyst consensus, surprise panel, or universal adjusted-EPS mapping. |
| Alpha Vantage | An earnings-history endpoint with annual and quarterly EPS; quarterly records include estimates and surprise metrics. A separate calendar endpoint covers expected events. | Small prototypes, notebooks, and symbol-level research that need a simple response. | The official support page currently states up to 25 free requests per day for most datasets; confirm endpoint eligibility, history, and commercial rights before relying on it. |
| Financial Modeling Prep | A documented earnings-calendar response with announcement dates, estimated EPS, and actual EPS for public companies. | Calendar screens and workflows that need estimated and actual values in one normalized interface. | Plan access, historical depth, revision behavior, and redistribution rights can change; verify the current entitlement instead of assuming every documented field is free. |
| Company releases plus filings | Management-presented GAAP and non-GAAP results, tables, explanations, and the primary disclosure context. | High-confidence verification and custom extraction for a smaller company universe. | Document discovery, table extraction, taxonomy mapping, corrections, and scaling must be engineered locally. |
A practical hybrid is to use a calendar or market-data API for discovery, then reconcile important reported values against the release or filing. Store both records rather than replacing one with the other: the vendor record preserves delivery behavior and consensus context, while the primary source preserves what the issuer formally disclosed.
How to evaluate a free plan before integration
| Check | Question to ask | Why it matters |
|---|---|---|
| Coverage | Which exchanges, security types, and historical years are included? | A global label may hide US-only or large-cap-only records. |
| Data timing | When do scheduled dates, confirmations, results, and revisions appear? | Calendars and live alerts tolerate different delays. |
| Point-in-time estimates | Are consensus snapshots timestamped and available before and after each result? | Latest-only consensus creates look-ahead bias. |
| Revisions | Are actuals, estimates, surprise fields, and source changes versioned? | Silent rewrites make historical results irreproducible. |
| Completeness | How are missing estimates, cancelled events, duplicate sources, and inactive securities represented? | Zeros and dropped rows can bias samples. |
| Request limits | What are the per-minute, daily, and monthly quotas? | A high monthly quota can still fail during earnings season bursts. |
| License | Are caching, redistribution, display, and commercial use allowed? | Technical access does not grant every product right. |
Build a small earnings-data acceptance test
Do not evaluate an API with one familiar ticker and one clean quarter. Build a compact truth set that forces the provider to reveal how it handles identity, timing, accounting variants, revisions, and missing data. Ten carefully chosen events usually expose more than hundreds of unchecked rows.
Include a normal US quarter, a loss with negative EPS, an estimate near zero, a split, a fiscal-year change, an ADR or cross-listing, a late schedule change, a corrected filing, a company-adjusted result, and a security that later delisted.
For every event, compare the issuer publication time, regulator acceptance time, and provider arrival time. A correct number that arrives after the alert window still fails a real-time use case.
Rebuild absolute and percentage surprise from the selected actual and estimate versions. Verify currency, diluted or basic share basis, split adjustment, denominator policy, and rounding before accepting the vendor result.
Define required-field completeness, maximum arrival lag, duplicate tolerance, identity match rate, revision retention, and reconciliation thresholds. Record a failure as missing, late, ambiguous, inconsistent, or unauthorized rather than one generic error.
A reliable integration workflow
- Write the research cutoff policy first: define which estimate snapshot, event timestamp, accounting basis, and market session belong in each historical row.
- Ingest company and event identities before facts, and preserve expected, confirmed, actual, provider-arrival, and revision times as separate columns.
- Append actual and estimate versions instead of overwriting them; derive surprise fields from explicitly selected component versions.
- Schedule calendar refreshes separately from post-announcement result polling, back off on HTTP 429 responses, cache stable history, and expose quota usage.
- Re-fetch recent events because report times, EPS values, and estimates may be corrected, then rerun only the affected derived features.
- Test split-adjusted and unadjusted EPS, negative and near-zero estimates, missing consensus, cross-listed symbols, fiscal-year changes, cancelled events, and daylight-saving boundaries.
Use QVeris to discover the right earnings capability
QVeris helps agents discover and inspect historical earnings, estimates, events, and filing capabilities before calling them. Compare schemas, coverage, authentication, limits, timestamps, and version behavior against the research contract. QVeris can simplify capability access; the application still owns point-in-time cutoffs, identity mapping, surprise formulas, revision history, and bias controls.
Open the QVeris tool details to inspect available capabilities, inspect inputs and outputs, and choose an interface your application can validate. For broader context, compare this guide with the REST API reference and QVeris Finance provider.
FAQ
Often, but depth varies. Some plans expose only recent quarters, latest-only estimates, or a limited symbol universe, so verify point-in-time history with difficult sample companies.
Not necessarily. Scheduled dates may update daily, while reported results may arrive minutes or hours after release. Measure source-to-provider delay separately from API response time.
Each actual, estimate, event status, and correction has an availability timestamp and retained prior versions. A query can reconstruct only the information available at a chosen historical cutoff.
Keep the absolute difference and flag percentage surprise as unstable or unavailable when the estimate is zero, near zero, or opposite in sign. Publish the formula and threshold.
Reported filings and normalized datasets may use different split-adjustment states. Store the adjustment basis and factor, and compare actual and estimate EPS only when both use the same basis.
Yes if it includes actual release times, pre-release estimate snapshots, stable securities, market sessions, revisions, and an unbiased historical universe. Calendar dates alone are insufficient.