# How to get an earnings calendar as data

Report dates as CSV or JSON, from a free key up — and what the rows leave out, which is whether a date is confirmed, the time of day and which quarter.

*https://stockmarketstack.com/how-to/get-an-earnings-calendar-as-data · next to Stock Market Data APIs*

**Answer:** An earnings calendar is one request on most market-data keys. Alpha Vantage returns the next three, six or twelve months as CSV on a free key; Finnhub, Financial Modeling Prep and EODHD return JSON windows with estimates and actuals. None of those four says whether a date is confirmed or projected, most leave the release time blank, and the quarter label is the company's fiscal one. Key rows on the period, not the date.

## The tools that do this

*In the order this page recommends trying them. Paid placement does not affect this order.*

1. [Alpha Vantage](https://stockmarketstack.com/tools/alpha-vantage.md) — One call returns the full scheduled list for the next 3, 6 or 12 months as CSV, on a free key. Forward only, and the timing column is mostly blank.
2. [Finnhub](https://stockmarketstack.com/tools/finnhub.md) — JSON by date window with fiscal year and quarter, a bmo, amc or dmh hour and non-GAAP EPS. The free key reaches one month back; non-US is opt-in.
3. [Financial Modeling Prep](https://stockmarketstack.com/tools/financial-modeling-prep.md) — JSON windows of up to 90 days with a lastUpdated date on each row. Free is a month of history on a sample list; Starter adds a year of US.
4. [EODHD](https://stockmarketstack.com/tools/eodhd.md) — Report date and period end as separate fields, history back to the 1990s, one call per request. From $19.99 a month as an add-on, not on the free plan.
5. [Massive](https://stockmarketstack.com/tools/massive.md) — Benzinga's earnings feed, the only one here with a projected-or-confirmed status, from $99 a month on an individual plan. Records start 30 April 2010.

## The short way

[Alpha Vantage](https://stockmarketstack.com/tools/alpha-vantage) returns the whole forward calendar in one request, on a free
key, as CSV:

```bash
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:

```text
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](https://stockmarketstack.com/tools/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](https://stockmarketstack.com/tools/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](https://stockmarketstack.com/tools/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](https://stockmarketstack.com/tools/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](https://stockmarketstack.com/tools/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](https://stockmarketstack.com/tools/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](https://stockmarketstack.com/tools/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:

```python
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](https://stockmarketstack.com/glossary/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](https://stockmarketstack.com/glossary/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](https://stockmarketstack.com/tools/sec-edgar) lists a filing's
items and its acceptance time in the free submissions JSON — [how to get SEC filings as
data](https://stockmarketstack.com/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](https://stockmarketstack.com/glossary/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](https://stockmarketstack.com/tools/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](https://stockmarketstack.com/categories/market-data-apis) you already hold a key for —
[how to get news headlines as data](https://stockmarketstack.com/how-to/get-news-headlines-as-data) is the adjacent build, and
[what financial data is genuinely free](https://stockmarketstack.com/guides/free-financial-data-sources) is the wider list.

## FAQ

### Is there a free earnings calendar API?

Several, each with a different edge. Alpha Vantage's EARNINGS_CALENDAR is not marked premium, and one request returns every scheduled report for the next three, six or twelve months as CSV — which matters on a key capped at 25 requests a day. Finnhub's free key gets one month of history plus new updates. Financial Modeling Prep's free Basic plan gets one month of history on a sample list of 87 symbols. EODHD's calendar is not on its free package; the cheapest route is a $19.99-a-month add-on.

### How do I know whether an earnings date is confirmed?

From most APIs, you do not. Alpha Vantage, Finnhub, Financial Modeling Prep and EODHD document no field for it, so a date the company has announced and a date the vendor projected come back in the same column. Benzinga's feed is the exception — date_confirmed is 1 or 0 on Benzinga's own API, and date_status is projected or confirmed where Massive resells it. Otherwise the confirmation is the company's own announcement, and you have to record it yourself.

### Why does a January report show up as Q1 of the next year?

Because the label is the company's fiscal quarter, not the calendar one. Finnhub's own sample response has Apple reporting on 28 January 2020 as quarter 1 of 2020 — Apple's fiscal year starts in October, so that is the October to December 2019 quarter. EODHD files the same kind of report under the date the period ended instead, and Alpha Vantage under fiscalDateEnding. Join on the period end date and the labels stop mattering.

### Can I get past earnings dates as well as upcoming ones?

Yes, except from Alpha Vantage's calendar, which only looks forward. Finnhub, Financial Modeling Prep and EODHD all take a from and to date that can sit in the past — how far back depends on the tier, from one month free to the 1990s on EODHD — and Massive's Benzinga feed starts on 30 April 2010. What they return is the date the report actually happened, not the date the calendar showed a month before it. That earlier version is only yours if you stored it.

## Sources

1. [Alpha Vantage API Documentation — Earnings Calendar](https://www.alphavantage.co/documentation/) — Alpha Vantage, read 2026-09-26
2. [Earnings Calendar API](https://finnhub.io/docs/api/earnings-calendar) — Finnhub, read 2026-09-26
3. [Earnings Calendar API](https://site.financialmodelingprep.com/developer/docs/stable/earnings-calendar) — Financial Modeling Prep, read 2026-09-26
4. [Pricing Plans](https://site.financialmodelingprep.com/pricing-plans) — Financial Modeling Prep, read 2026-09-26
5. [Calendar API — Upcoming Dividends, Earnings, Trends, IPOs and Splits](https://eodhd.com/financial-apis/calendar-upcoming-earnings-ipos-and-splits) — EODHD, read 2026-09-26
6. [Benzinga Earnings — REST API](https://massive.com/docs/rest/partners/benzinga/earnings) — Massive, read 2026-09-26
7. [Earnings — Calendar API reference](https://docs.benzinga.com/api-reference/calendar-api/get-earnings) — Benzinga, read 2026-09-26
8. [Apple reports first quarter results](https://www.apple.com/newsroom/2025/01/apple-reports-first-quarter-results/) — Apple, 2025-01-30
9. [EDGAR Application Programming Interfaces](https://www.sec.gov/search-filings/edgar-application-programming-interfaces) — U.S. Securities and Exchange Commission, read 2026-09-26

*Last updated 2026-09-26. A reference page, corrected in place — not a dated post.*