# Earnings

The earnings endpoint provides comprehensive earnings data for a specified company, including both the estimated and actual Earnings Per Share (EPS) figures. This endpoint delivers historical earnings information, allowing users to track a company's financial performance over time.

**API credits cost:** `20` per symbol

> **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

- `symbol` (string, optional, see notes)
  Symbol ticker of instrument.
For preferred stocks use dot(.) delimiter.
E.g. `BRK.A` or `BRK.B` will be correct
  Example value: `AAPL`


- `figi` (string, optional, see notes)
  Filter by financial instrument global identifier (FIGI). This parameter is available on the Ultra plan (individual) and the Enterprise plan (business) and above.
  Example value: `BBG000B9Y5X2`


- `isin` (string, optional, see notes)
  Filter by international securities identification number (ISIN). ISIN access is activating in the Data add-ons section
  Example value: `US0378331005`


- `cusip` (string, optional, see notes)
  The CUSIP of an instrument for which data is requested. CUSIP access is activating in the Data add-ons section
  Example value: `594918104`


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


- `type` (string, optional)
  The asset class to which the instrument belongs
  Example value: `Common Stock`
  Available values: `American Depositary Receipt`, `Bond`, `Bond Fund`, `Closed-end Fund`, `Common Stock`, `Depositary Receipt`, `Digital Currency`, `ETF`, `Exchange-Traded Note`, `Global Depositary Receipt`, `Limited Partnership`, `Mutual Fund`, `Physical Currency`, `Preferred Stock`, `REIT`, `Right`, `Structured Product`, `Trust`, `Unit`, `Warrant`


- `period` (string, optional)
  Type of earning, returns only 1 record.
When is not empty, dates and outputsize parameters are ignored
  Available values: `latest`, `next`


- `outputsize` (integer, optional)
  Number of data points to retrieve.
Supports values in the range from `1` to `1000`.
Default `10` when no date parameters are set, otherwise set to maximum
  Default value: `10`


- `format` (string, optional)
  The format of the response data
  Available values: `JSON`, `CSV`
  Default value: `JSON`


- `delimiter` (string, optional)
  The separator used in the CSV response data
  Default value: `;`


- `dp` (integer, optional)
  The number of decimal places in the response data. Should be in range [0,11] inclusive
  Default value: `2`


- `start_date` (string, optional)
  The date from which the data is requested. The date format is `YYYY-MM-DD`.
  Example value: `2024-04-01`


- `end_date` (string, optional)
  The date to which the data is requested. The date format is `YYYY-MM-DD`.
  Example value: `2024-04-30`


**Notes:**

 - At least one of the following parameters is required: `symbol`, `figi`, `isin`, `cusip`.

## Response

- `meta` (object)
  Metadata about the instrument
  - `symbol` (string)
    Symbol of the instrument
  - `name` (string)
    Name of the company
  - `currency` (string)
    Currency in which the instrument is traded
  - `exchange` (string)
    Exchange where the instrument is traded
  - `mic_code` (string)
    Market identifier code (MIC) under ISO 10383 standard
  - `exchange_timezone` (string)
    Timezone of the exchange

- `earnings` (array of object)
  List of earnings data
  - `date` (string)
    Date of earning release
  - `time` (string)
    Time of earning release, 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 the percentage of the `eps_actual` related to `eps_estimate`

- `status` (string)
  Response status


## Example Request

```bash
curl "https://api.twelvedata.com/earnings?symbol=AAPL&apikey=demo"
```

## Example Response

```json
{
    "meta": {
        "symbol": "AAPL",
        "name": "Apple Inc",
        "currency": "USD",
        "exchange": "NASDAQ",
        "mic_code": "XNAS",
        "exchange_timezone": "America/New_York"
    },
    "earnings": [
        {
            "date": "2020-04-30",
            "time": "After Hours",
            "eps_estimate": 2.09,
            "eps_actual": 2.55,
            "difference": 0.46,
            "surprise_prc": 22.01
        }
    ],
    "status": "ok"
}
```