# Earnings calendar

The earnings calendar endpoint provides a schedule of company earnings announcements for a specified date range. By default, it returns earnings data for the current day. Users can customize the date range using the `start_date` and `end_date` parameters to retrieve earnings information for specific periods. This endpoint is useful for tracking upcoming earnings reports and planning around key financial announcements.

**API credits cost:** `40` per request

> **Note:** This API endpoint is available on the <a href="https://twelvedata.com/pricing">Grow</a> plan (individual) and the <a href="https://twelvedata.com/pricing-business">Venture</a> plan (business) and above.

## Parameters

- `exchange` (string, optional)
  Exchange where instrument is traded
  Example value: `NASDAQ`


- `mic_code` (string, optional)
  Market Identifier Code (MIC) under ISO 10383 standard
  Example value: `XNAS`


- `country` (string, optional)
  Country where instrument is traded, e.g., `United States` or `US`
  Example value: `United States`


- `format` (string, optional)
  Value can be JSON or CSV
  Available values: `JSON`, `CSV`
  Default value: `JSON`


- `delimiter` (string, optional)
  Specify the delimiter used when downloading the CSV file
  Default value: `;`


- `dp` (integer, optional)
  Specifies the number of decimal places for floating values.
Should be in range [0,11] inclusive
  Default value: `2`


- `start_date` (string, optional)
  Can be used separately and together with end_date.
Format `2006-01-02` or `2006-01-02T15:04:05`
  Example value: `2024-04-01`


- `end_date` (string, optional)
  Can be used separately and together with start_date.
Format `2006-01-02` or `2006-01-02T15:04:05`
  Example value: `2024-04-30`



## Response

- `earnings` (map (key: string, value: array of object))
  Map of dates to earnings data
  - `symbol` (string)
    Instrument symbol (ticker)
  - `name` (string)
    Full name of instrument
  - `currency` (string)
    Currency in which instrument is traded by ISO 4217 standard
  - `exchange` (string)
    Exchange where instrument is traded
  - `mic_code` (string)
    Market identifier code (MIC) under ISO 10383 standard
  - `country` (string)
    Country where exchange is located
  - `time` (string)
    Can be either of the following values: `Pre Market`, `After Hours`, `Time Not Supplied`
  - `eps_estimate` (number)
    Analyst estimate of the future company earning
  - `eps_actual` (number)
    Actual value of reported earning
  - `difference` (number)
    Delta between `eps_actual` and `eps_estimate`
  - `surprise_prc` (number)
    Surprise in percentage of the `eps_actual` related to `eps_estimate`

- `status` (string)
  Response status


## Example Request

```bash
curl "https://api.twelvedata.com/earnings_calendar?apikey=your_api_key"
```

## Example Response

```json
{
    "earnings": {
        "2020-04-30": [
            {
                "symbol": "BR",
                "name": "Broadridge Financial Solutions Inc",
                "currency": "USD",
                "exchange": "NYSE",
                "mic_code": "XNYS",
                "country": "United States",
                "time": "Time Not Supplied",
                "eps_estimate": 1.72,
                "eps_actual": 1.67,
                "difference": -0.05,
                "surprise_prc": -2.9
            }
        ]
    },
    "status": "ok"
}
```