Your Guide to Earnings API: Estimates, Actuals, Surprises, and Revisions

Four times a year, every US public company tells the market what it actually earned. Analysts have already published what they expected. The gap between those two numbers moves stock prices more reliably than almost any other scheduled event, and the way expectations shift in the weeks before and after tells you as much as the report itself.

That makes earnings one of the most valuable datasets in finance and one of the most annoying to assemble. Actuals live in filings. Estimates live with the analysts who publish them. Consensus is a moving target that changes daily. Surprise is a calculation that depends on getting both sides aligned to the same fiscal period, for the same company, at the same point in time.

An earnings API solves the assembly problem. It delivers estimates, actuals, surprises, and revision history as structured records keyed to a company and a fiscal period, so you can query the relationship instead of reconstructing it.

What an Earnings API Provides

An earnings data API is a delivery layer over the full expectation-and-outcome cycle for a company's results. In practice that means five categories of data.

Consensus estimates. The aggregated view of what Wall Street expects a company to report, usually for the current quarter, the next quarter, the current fiscal year, and the following fiscal year. A useful consensus record includes more than the mean: it carries the high estimate, the low estimate, the standard deviation, and the number of analysts contributing, because dispersion tells you how confident the street actually is.

Actual reported results. The number the company delivered, tied to the fiscal period it covers rather than the date it was announced. Those are different, and conflating them is one of the most common ways an earnings model quietly breaks.

Surprises. The difference between actual and consensus, expressed in both absolute and percentage terms.

Revisions. The history of how consensus moved over time, which is only available if the provider stores estimates as a time series rather than overwriting the current value.

Announcement dates. Confirmed and expected report dates, which is what drives earnings calendars, pre-earnings screens, and event-window studies.

Underneath all of it sits entity resolution. A ticker, a CIK, or an internal security ID has to resolve to the same company, and the fiscal period on an estimate has to line up with the fiscal period on the actual. Companies with non-calendar fiscal years, ticker changes, and mergers are where this gets hard, and it is the main reason teams stop building this in-house.

Earnings Estimates, Actual Results, and Consensus Data

An estimate starts at the analyst level. A covering analyst publishes a forecast for a company's EPS in a given fiscal period, updates it as new information arrives, and that forecast is one input into a consensus.

Consensus is the aggregation. The mean is what most people quote, but the underlying distribution is where the signal lives. Twelve analysts clustered within two cents of each other is a very different setup from twelve analysts spread across forty cents, even when the mean is identical. Dispersion is a tradeable feature, and it only exists if your provider gives you high, low, count, and standard deviation alongside the mean.

Actuals come from the company. For most purposes the number you want is the reported figure tied to the fiscal quarter or fiscal year, joined to the estimate on that same period key. Intrinio's EPS Estimates feed keeps consensus and historical actuals in the same dataset for exactly this reason, so the join is already done for you.

One detail worth flagging: estimates data can be reported on a GAAP or a non-GAAP basis, and the two are not interchangeable. Intrinio's estimates are GAAP. If you are comparing consensus against a company's own adjusted EPS from a press release, you are comparing two different measurements, and the surprise you calculate will be wrong.

Earnings are also not the only line that gets forecast. Sales estimates matter because revenue is harder to manage than earnings, so a revenue miss on an EPS beat is a different story than a clean beat. EBITDA estimates feed enterprise value work, and long term growth estimates feed anything that needs a terminal growth assumption.

How Earnings Surprises Are Calculated

The math is simple. The discipline around it is not.

Absolute surprise is the actual result minus the consensus estimate. Percentage surprise divides that difference by the absolute value of the consensus:

Surprise % = (Actual EPS - Consensus EPS) / |Consensus EPS| x 100

Three things break this in production.

Small or negative denominators. When consensus EPS is 0.01 and a company reports 0.03, the percentage surprise is 200%. When consensus is negative, the sign of the percentage stops meaning what you think it means. Serious pipelines either cap percentage surprise, switch to a standardized measure that scales the surprise by the dispersion of estimates, or fall back to the absolute difference for near-zero periods.

Which consensus you use. The correct comparison is the consensus as it stood immediately before the announcement, not the consensus you pull today. Estimates continue to change after a company reports, so a backtest built on current-value consensus is looking at information that did not exist on the trade date. This is the single most common source of lookahead bias in earnings research.

Period alignment. The estimate and the actual have to describe the same fiscal period. For companies with fiscal years that do not end in December, calendar-quarter logic will silently misalign them.

A dedicated EPS Surprises feed handles the alignment and the point-in-time question for you, and returns the estimate, the actual, the surprise, and the announcement date as one record. Sales Surprises does the same on the revenue line.

Tracking Estimate Revisions Over Time

Revisions are where estimate data stops being a snapshot and starts being a signal.

A revision is a change in consensus between two points in time. What matters is usually not the size of any single change but the direction and breadth of many: how many analysts moved, which way, and how quickly. Sustained upward revision momentum ahead of a report is one of the more durable anomalies in the literature, and the drift after a surprise is another.

Capturing this requires history, and specifically point-in-time history. A provider that overwrites the current consensus each night gives you today's number and nothing else. A provider that stores every consensus value as of every date lets you reconstruct what the market believed on any given day, which is the only way to build a revision series you can trust in a backtest.

Intrinio offers 20+ years of estimate history across its estimates feeds. History is a one-time add-on rather than part of the default plan, which is worth knowing before you scope a research project around it. Analyst-level estimates take this a layer deeper, letting you follow individual contributors rather than only the aggregate, and price targets give you the valuation side of the same revision behavior.

Using Earnings Data in Research and Financial Applications

Quantitative research. Surprise and revision series are standard factor inputs. Post-earnings announcement drift, revision momentum, and dispersion-based strategies all start with a clean point-in-time panel of estimates and actuals.

Screening and discovery. Consensus growth, forward multiples, and beat and miss streaks are among the most-used filters in any equity screener, and they need estimate data joined to fundamentals to work.

Earnings calendars and alerts. Confirmed and expected announcement dates drive the calendar view in nearly every retail and professional platform, and they are what trigger notifications when a company reports.

Valuation. Forward EPS and long-term growth rates are direct inputs to forward multiples and to the terminal value in a discounted cash flow model.

Risk and positioning. Knowing which holdings report next week, and how wide the estimate range is on each, is a basic input to event risk management.

AI research applications. An LLM asked what a company is expected to earn should be reading a structured estimate record, not generating one. Pairing consensus and surprise data with fundamentals and filing text gives an agent something it can cite instead of approximate.

Access Earnings Data With Intrinio

Intrinio delivers earnings data through its Estimates feeds: EPS Estimates, EPS Surprises, Sales Estimates, Sales Surprises, EBITDA Estimates, Long Term Growth, Analyst Estimates, and Price Targets. Consensus, historical actuals, surprise tracking, and revision history come from the same source, normalized to consistent company and period identifiers so the joins are already done.

The estimates feeds are available on the Enterprise plan, with 20+ years of history available as an add-on. Delivery runs over REST, bulk download, and the Intrinio MCP server, so the same earnings history can back a nightly research job, a production screener, or an AI agent without a second integration. Endpoint-level detail lives in the API documentation.

If you want to see how the estimates and surprise data lines up against your universe before committing, the fastest path is a conversation with our team.

Request Enterprise Access or review plans and pricing to see what fits.

‍