Earnings Calendar API

Parameters

At least one of ticker, date, date_start, or date_end must be provided. date cannot be combined with date_start or date_end.

• ticker  optional

  Company ticker symbol (e.g., MSFT). If provided, returns earnings data for that specific company.

• date  optional

  Date in YYYY-MM-DD format (e.g., 2024-01-15). If provided, returns all earnings data for that specific date.

• date_start  optional

  Start date of a range in YYYY-MM-DD format (e.g., 2024-01-15). Inclusive. If only date_start is provided, date_end defaults to 7 days later. Cannot be combined with date.

• date_end  optional

  End date of a range in YYYY-MM-DD format (e.g., 2024-01-22). Inclusive. Must be on or after date_start. If only date_end is provided, date_start defaults to 7 days earlier. Cannot be combined with date.

• show_upcoming  optional premium only

  Whether to show upcoming earnings dates. Must be either true or false. If unset, the default value is false.

• offset  optional

  Number of results to skip for pagination. Must be a non-negative integer. Each request returns up to 50 results; use offset to page through larger result sets (e.g. offset=50 for the next 50 results).

Headers

• X-Api-Key  required

  API Key associated with your account.

Response

A JSON array of objects, each containing the following fields, or an error if the request is unsuccessful.

• date

  The date of the earnings.

• ticker

  The ticker symbol of the company.

• fiscal_year

  The company's fiscal year for this earnings report.

• fiscal_quarter

  The company's fiscal quarter (1-4) for this earnings report.

• earnings_timing  premium only

  Timing of the earnings call. Possible values are:

  • before_market: Earnings call occurs before the market opens.

  • during_market: Earnings call occurs during regular market hours.

  • after_market: Earnings call occurs after the market closes.

• earnings_call_timestamp  premium only

  Unix timestamp of when the earnings call occurred or is scheduled to occur.

• actual_revenue

  The actual revenue in USD.

• estimated_revenue  premium only

  The estimated revenue in USD.

• revenue_difference  premium only

  The difference between actual and estimated revenue (actual_revenue - estimated_revenue), in USD.

• revenue_difference_pct  premium only

  The revenue difference as a percentage of the estimate: (actual_revenue - estimated_revenue) / |estimated_revenue| * 100. Null when estimated_revenue is 0.

• actual_eps

  The actual earnings per share in USD.

• estimated_eps  premium only

  The estimated earnings per share in USD.

• eps_difference  premium only

  The difference between actual and estimated EPS (actual_eps - estimated_eps), in USD.

• eps_difference_pct  premium only

  The EPS difference as a percentage of the estimate: (actual_eps - estimated_eps) / |estimated_eps| * 100. Null when estimated_eps is 0.

Note for free tier users: Premium-only fields are still included in the response, but their values are replaced with a message indicating the field requires a premium subscription. Upgrade at /pricing to unlock real values.

Parameters

This endpoint does not require any parameters.

Headers

• X-Api-Key  required

  API Key associated with your account.

Response

A JSON array of objects, each containing the following fields, or an error if the request is unsuccessful.

• ticker

  The company ticker symbol.

• company

  The company name.

Parameters

All parameters are optional. If no parameters are provided, returns upcoming earnings from today onwards (up to 100 results).

• start_date  optional

  Start date in YYYY-MM-DD format (e.g., 2024-01-15). Must be today or later. Defaults to today if not provided.

• end_date  optional

  End date in YYYY-MM-DD format (e.g., 2024-12-31). Must be after start_date. Defaults to 10 years from today if not provided.

• date  optional

  Single date in YYYY-MM-DD format (e.g., 2024-01-15). If provided, overrides start_date and end_date to filter by this exact date.

• exchange  optional

  Exchange code to filter by (e.g., NASDAQ, NYSE, HKSE, LSE, TSX). Returns only earnings from companies listed on the specified exchange.

• ticker  optional

  Ticker symbol to filter by (e.g., AAPL, 0700.HK). Returns only earnings for that specific company.

• limit  optional

  Maximum number of results to return. Must be between 1 and 100 (inclusive). Default is 100.

• offset  optional

  Number of results to skip for pagination. Must be a non-negative integer. Use in combination with limit to paginate through results.

Headers

• X-Api-Key  required

  API Key associated with your account.

Response

A JSON array of objects, each containing the following fields, or an error if the request is unsuccessful.

• ticker

  The ticker symbol of the company.

• date

  The date of the upcoming earnings (YYYY-MM-DD format).

• eps_estimated

  The estimated earnings per share in USD (may be null).

• revenue_estimated

  The estimated revenue in USD (may be null).

• exchange

  The exchange code where the company is listed (e.g., NASDAQ, NYSE, HKSE).

• earnings_timing

  Timing of the earnings call. Omitted when the company's earnings timing is not yet known. Possible values are:

  • before_market: Earnings call occurs before the market opens.

  • during_market: Earnings call occurs during regular market hours.

  • after_market: Earnings call occurs after the market closes.