How to get an earnings calendar as data

The short way

Alpha Vantage returns the whole forward calendar in one request, on a free key, as CSV:

curl "https://www.alphavantage.co/query?function=EARNINGS_CALENDAR&horizon=3month&apikey=YOUR_API_KEY"

horizon takes 3month, 6month or 12month and defaults to three; adding symbol=IBM narrows the file to one company. What comes back is seven columns:

symbol,name,reportDate,fiscalDateEnding,estimate,currency,timeOfTheDay
IBM,INTERNATIONAL BUSINESS MACHINES CORPORATION,2026-10-21,2026-09-30,2.9,USD,post-market
ADXN,ADDEX THERAPEUTICS LIMITED,2026-09-28,2026-06-30,,USD,pre-market
AIAI,AIAI HOLDINGS CORPORATION,2026-09-28,2026-06-30,,USD,

That is the shape every provider below returns in some form: who, on what day, for which period, against what estimate, and — sometimes — at what time of day. The documentation's own demo request, run on 26 September 2026, returned 4,622 rows between 28 September and 22 December. One request for the whole quarter is the reason to start here: the free key allows 25 a day.

Read the last two rows before you build on it. One has no estimate, one has no time of day, and nothing on either row says whether 28 September is a date the company announced or one somebody projected. That is what the rest of this page is about.

What the options are

The whole forward calendar in one file. Alpha Vantage as above. The endpoint looks forward only — there is no from parameter and no history — and the licence on every plan is personal and non-commercial.

A date window, JSON, with fiscal labels. Finnhub's /calendar/earnings takes from, to and an optional symbol, and returns date, hour, year, quarter, epsEstimate, epsActual, revenueEstimate and revenueActual. Non-US listings are excluded unless you pass international=true. The free key is documented as reaching one month of historical earnings plus new updates, at 60 calls a minute.

A window with a last-changed date. Financial Modeling Prep's /stable/earnings-calendar takes from and to, and the documentation caps a window at 90 days and 4,000 records, so a year is at least five requests. Each row carries symbol, date, epsActual, epsEstimated, revenueActual, revenueEstimated and lastUpdated. The pricing grid gives the free Basic plan one month of history on a sample list of 87 symbols, Starter a year of US listings, Premium five years across the US, UK and Canada, and Ultimate global coverage. The legacy /api/v3 calendar carried a before-or-after time field; the stable one does not by default, and the parameter table lists an includeReportTimes flag without documenting what it adds — check it against your own key.

The deepest history, and the report date split from the period. EODHD's /api/calendar/earnings returns report_date — the day results come out — separately from date, the end of the fiscal period they cover, together with before_after_market, currency, actual, estimate, difference and percent. The vendor measured coverage back to the 1990s and 26,414 reports already scheduled through the end of 2027. Every request costs one call whatever its size. It ships in the $59.99 Fundamentals and $99.99 All-In-One plans, or on its own as the $19.99-a-month Corporate Events Calendar & News add-on. Two defaults catch people: output is CSV unless you pass fmt=json, and symbols filters a date window rather than replacing it, so a single-ticker request with no dates searches the next seven days and usually comes back empty. Always pass from and to.

A confirmation status. Massive resells Benzinga's earnings dataset at /benzinga/v1/earnings for $99 a month on an individual plan, with business use by quote and records back to 30 April 2010. It is the one route on this page with a field saying whether the date is projected or confirmed, a time of day, fiscal_period values that include H1 and FY for companies that do not report quarterly, and an eps_method naming the basis of the number. Results sort by last_updated, newest first, which makes an incremental pull cheap. Benzinga also licenses the same calendar directly, contracted and priced the way the Benzinga News API is.

A calendar to look at rather than ingest. If the goal is to see the dates for your own holdings rather than to store them, that is a portfolio app, not an API — Stock Events is built around exactly that screen.

Where this breaks

Confirmed and projected dates share one column. Until a company announces its report date, any date a vendor shows is the vendor's own projection. Alpha Vantage's CSV, Finnhub's schema, Financial Modeling Prep's stable response and EODHD's schema have no field that tells the two apart. Benzinga's does: date_confirmed is 1 or 0 on Benzinga's own API, and date_status is projected or confirmed where Massive resells it. Benzinga's documentation example is Apple on 29 October 2026 with date_confirmed at 0 — and Alpha Vantage's file lists Apple on the same day, with nothing to say which kind of date it is. Give your table a status column, write unknown where the vendor is silent, and never let a projection drive something that needs the real date.

The time of day is usually missing, and five vendors spell it five ways. In the Alpha Vantage file above, 4,360 of 4,622 rows had an empty timeOfTheDay; 160 said pre-market and 102 post-market. Finnhub's hour is bmo, amc or dmh — during market hours, a value the others have no word for. EODHD's before_after_market is BeforeMarket, AfterMarket or null. Massive's time is a clock time. Benzinga's schema describes time as bmo or amc while its own example response carries 16:00:00. Map them into one vocabulary with an explicit unknown, because a missing value that defaults to after the close is a wrong value nobody can see:

TIMING = {
    "pre-market": "before_open", "post-market": "after_close",      # Alpha Vantage
    "bmo": "before_open", "amc": "after_close", "dmh": "during_hours",  # Finnhub, Benzinga
    "BeforeMarket": "before_open", "AfterMarket": "after_close",    # EODHD
}

def timing(raw):
    return TIMING.get(raw or "", "unknown")

A clock time such as 16:00:00 belongs in its own column, next to the zone it was written in.

Dates move, and most feeds overwrite rather than record the move. When a company confirms a date different from the projection, or reschedules, the row changes in place. Financial Modeling Prep stamps each row with a lastUpdated date, Benzinga with an updated Unix timestamp and Massive with last_updated; Alpha Vantage, Finnhub and EODHD document nothing of the kind. None of them hands you the previous value. If you need to know what the calendar said last week — for an audit, or because a job ran on the old date — the only source is your own daily snapshot. Key it on the company and the fiscal period end, never on the report date, because the report date is the field that changes. It is the point-in-time problem at the scale of a single column.

The quarter is the company's fiscal quarter. Finnhub's own sample response has Apple reporting on 28 January 2020 as quarter: 1, year: 2020 — Apple's fiscal year starts in October, so that is the October to December 2019 quarter. Benzinga's example files the 29 October 2026 report as Q4 of 2026. EODHD sidesteps labels and gives the period end instead, but its example records Apple's report of 30 January 2025 against 2024-12-31, while Apple's own release says the quarter ended on 28 December 2024. In Alpha Vantage's three-month file, 165 rows had a fiscalDateEnding outside March, June, September and December. And companies that report half- yearly arrive as H1 or FY on Massive, not as a quarter at all. Join periods on an end date with a few days' tolerance, and keep the vendor's label only for display.

"EPS estimate" is several different numbers. Finnhub documents its EPS as non-GAAP, with estimates drawn from both sell-side and buy-side analysts and a revenue estimate that includes Finnhub's own. Benzinga has an eps_type field for GAAP or non-GAAP — empty in its own example — and Massive an eps_method of gaap, ffo or adj. Alpha Vantage's estimate, Financial Modeling Prep's epsEstimated and EODHD's estimate document no basis at all. Estimates are also often simply absent: 1,269 of the 4,622 Alpha Vantage rows had none, and EODHD returns difference as 0 rather than null when the estimate is missing, so test the estimate before trusting a zero. Currency is the last trap: Financial Modeling Prep's response has no currency field and its own tutorial notes EPS arrives in the trading currency — a Copenhagen listing in Danish kroner — and Finnhub's schema has none either. Two vendors' estimates for the same company are not interchangeable, and one vendor's estimates across currencies are not comparable without the column you have to add.

Every date is a local date with no zone attached. A report date says nothing about whose calendar it is on, and for a release made in Tokyo or Sydney the local date and the New York date can differ by one. Where a time exists it is no better: Massive formats time as HH:MM:SS EST, a label rather than an offset, while New York spends March to November on EDT. SEC EDGAR does it properly — the submissions JSON gives every filing an acceptanceDateTime in UTC, and Apple's Item 2.02 results filings were accepted at 20:30 UTC in July 2026 and 21:30 UTC in January 2026, both 16:30 in New York. Store an instant in UTC where you have a time, the exchange's zone name rather than a fixed offset where you do not, and convert only for display.

If you outgrow this

When the date has to be the real one, go to the filing rather than the calendar. US results are furnished on Form 8-K under Item 2.02, and SEC EDGAR lists a filing's items and its acceptance time in the free submissions JSON — how to get SEC filings as data covers the endpoint and its ten-requests-a-second limit. It tells you when a report happened, never when one is scheduled, so it corrects a calendar rather than replacing one.

When you need the estimate's history rather than its latest value, EODHD's /api/calendar/trends returns the consensus as it stood 7, 30, 60 and 90 days earlier, with counts of upward and downward revisions — the one endpoint here that keeps a past state for you.

When the calendar appears in front of other people, every self-serve plan on this page is licensed for personal use: showing the data in a product is redistribution. At Finnhub and Financial Modeling Prep that is a quoted Enterprise contract, at Alpha Vantage a separate agreement, and at EODHD even the $399-a-month Internal Use plan keeps the data inside the company. Budget for it before the screen is designed.

When confirmation status is the requirement, Benzinga's dataset through Massive is the self-serve answer, and the direct Benzinga licence is the one to price when the use is commercial.

Earnings dates are one endpoint on most general providers, so the choice is usually which market data API you already hold a key for — how to get news headlines as data is the adjacent build, and what financial data is genuinely free is the wider list.