List earnings calendar events

Return a filterable, market-wide page of earnings events. Events are per ticker: by default the collection spans every ticker; pass identifier to restrict it to one. The response symbol echoes the exact listing you requested.

Upcoming events carry the scheduled release date, session, and consensus estimates. Once a company reports, the same event fills in actuals and the EPS and revenue surprises. Events without a known release date are omitted.

GET/v3.0.0/calendar/earnings

Plan Access

Free

(Your plan)

Individual

$29/mo

Professional

$89/mo

Plan History

Free

(Your plan)

Not included

Individual

$29/mo

5 years

Professional

$89/mo

All available

Parameters

Query parameters

identifierstringoptional

Restrict results to a single ticker. Accepts an exchange and symbol separated by a colon (e.g. NASDAQ:AAPL), a ticker ID, or a FIGI; the response symbol echoes the listing you requested. Omit to list earnings events across all tickers.

Example: NASDAQ:AAPL
datestringoptional

Pass a YYYY-MM-DD date directly for an exact release-date match. For a range, combine the modifiers below, for example, date.gte=2026-07-01&date.lt=2026-08-01.

+ Show filter modifiers
date.gtestring

Return events whose release date is greater than or equal to the given date.

date.gtstring

Return events whose release date is strictly greater than the given date.

date.ltestring

Return events whose release date is less than or equal to the given date.

date.ltstring

Return events whose release date is strictly less than the given date.

orderstringoptional

Sort by release date (release_date).

Default: descValues: ascdesc
limitintegeroptional

Maximum number of resources to return.

Default: 100Min: 1Max: 500
pagestringoptional

Opaque page token from a previous response. Follow the returned page URL when possible.

Response

Each item is a v3.calendar.earnings_event. Results sort by release date in descending order by default; pass order=asc for oldest first. Scope the feed to one ticker with identifier.

Response fields

dataarray of objects

Array of earnings-event resources for the current page.

+ Show child attributes
idstring

Unique identifier for the earnings event, beginning with ern_.

objectstring

String representing the object's type, always v3.calendar.earnings_event for this resource.

symbolstring

Qualified symbol combining the exchange code and ticker separated by a colon, e.g. NASDAQ:AAPL. When you filter by identifier, this echoes the listing you requested.

exchangestring

Short code of the exchange where the ticker trades, e.g. NASDAQ.

period_end_datestring

Last day of the fiscal period the release reports on, in YYYY-MM-DD format. A company has exactly one event per fiscal period.

fiscal_periodstring

Label of the fiscal period the release reports on, always a four-digit fiscal year and a quarter joined by a dash: 2026-Q1, 2026-Q2, 2026-Q3, or 2026-Q4. Fiscal years may not align with calendar years. null when the period label is not yet assigned.

release_datestring

Date the company reports (or reported) results, in YYYY-MM-DD format. The calendar sorts and filters on this date.

release_timestring

Exact announcement time as an ISO 8601 UTC timestamp. null when only the date is known.

release_sessionstring

Trading session of the announcement: pre-market for before the open, post-market for after the close, or null when the session is not known.

is_confirmedboolean

Whether the company has confirmed the release date. false means the date is an estimate and may move.

is_reportedboolean

Whether results for the period have been reported. Reported events carry actuals and surprises; upcoming events carry only estimates.

eps_actualnumber

Reported earnings per share, in currency units. null until results are out.

eps_estimatenumber

Consensus earnings-per-share estimate ahead of the release, in currency units. null when no estimate is available.

eps_surprisenumber

Difference between actual and estimated EPS (eps_actual - eps_estimate). null until both sides exist.

eps_surprise_percentnumber

EPS surprise as a percentage of the estimate. Positive when the company beat expectations.

revenue_actualnumber

Reported revenue for the period, in currency units. null until results are out.

revenue_estimatenumber

Consensus revenue estimate ahead of the release, in currency units. null when no estimate is available.

revenue_surprisenumber

Difference between actual and estimated revenue (revenue_actual - revenue_estimate). null until both sides exist.

revenue_surprise_percentnumber

Revenue surprise as a percentage of the estimate. Positive when the company beat expectations.

currencystring

ISO 4217 code of the currency of the EPS and revenue fields, e.g. USD.

updated_atstring

ISO 8601 UTC timestamp of the last change to this event.

next_page_urlnullable

URL of the next page of results, or null when there are no more pages. Request it unchanged to continue paging.

previous_page_urlnullable

URL of the previous page of results, or null on the first page.

Examples

Combine the filters below to answer common questions. Each request is runnable.

Companies reporting during one week, using a date.gte lower bound and a date.lt upper bound on the release date:

curl "https://api.roic.ai/v3.0.0/calendar/earnings?apikey=YOUR_API_KEY&date.gte=2026-07-27&date.lt=2026-08-03&order=asc"

The earnings history and upcoming schedule for one ticker:

curl "https://api.roic.ai/v3.0.0/calendar/earnings?apikey=YOUR_API_KEY&identifier=NASDAQ:AAPL&order=desc"

Events released on one exact date:

curl "https://api.roic.ai/v3.0.0/calendar/earnings?apikey=YOUR_API_KEY&date=2026-04-30"

Related endpoints

Request
curl "https://api.roic.ai/v3.0.0/calendar/earnings?apikey=YOUR_API_KEY&identifier=NASDAQ:AAPL&order=desc"
Response
200 OK
{
  "data": [
    {
      "id": "ern_QpJrDTduBoORk8",
      "object": "v3.calendar.earnings_event",
      "symbol": "NASDAQ:AAPL",
      "exchange": "NASDAQ",
      "period_end_date": "2026-03-31",
      "fiscal_period": "2026-Q2",
      "release_date": "2026-04-30",
      "release_time": "2026-04-30T20:30:00.000Z",
      "release_session": "post-market",
      "is_confirmed": true,
      "is_reported": true,
      "eps_actual": 2.01,
      "eps_estimate": 1.945766,
      "eps_surprise": 0.064234,
      "eps_surprise_percent": 3.3012191599,
      "revenue_actual": 111184000000,
      "revenue_estimate": 109457588844,
      "revenue_surprise": 1726411156,
      "revenue_surprise_percent": 1.5772420845,
      "currency": "USD",
      "updated_at": "2026-07-23T13:21:56.374Z"
    }
  ],
  "next_page_url": null,
  "previous_page_url": null
}