> ## Documentation Index
> Fetch the complete documentation index at: https://docs.davidhf.com/llms.txt
> Use this file to discover all available pages before exploring further.

# Earnings

> Earnings results, surprises, press releases, and the earnings calendar.

Earnings endpoints return quarterly/annual earnings results with consensus, actuals, surprises, and the synthetic press release, plus a forward-looking earnings calendar.

## Earnings

```http theme={null}
GET /earnings
```

Earnings results for a ticker (or across the scenario when `ticker` is omitted).

| Parameter     | Type    | Required | Default | Description             |
| ------------- | ------- | -------- | ------- | ----------------------- |
| `scenario_id` | string  | Yes      | -       | The world to read from. |
| `ticker`      | string  | No       | all     | Restrict to one ticker. |
| `as_of`       | date    | No       | -       | Point-in-time cutoff.   |
| `limit`       | integer | No       | 4       | Page size (max 500).    |
| `offset`      | integer | No       | 0       | Pagination offset.      |

<CodeGroup>
  ```bash cURL theme={null}
  curl -s "https://api.davidhf.com/earnings?scenario_id=<id>&ticker=AAPL" \
    -H "X-API-KEY: YOUR_API_KEY"
  ```

  ```python Python theme={null}
  dd.earnings.list("AAPL", scenario_id="<id>")
  ```
</CodeGroup>

```json theme={null}
{
  "earnings": [
    {
      "ticker": "AAPL",
      "report_period": "2026-03-31",
      "filing_date": "2026-04-24",
      "accession_number": "0000320193-26-000018",
      "fiscal_period": "Q1",
      "currency": "USD",
      "filing_datetime": "2026-04-24T16:30:00",
      "signals": { "revenue_surprise": 0.021, "eps_surprise": -0.014, "guidance": "cut" },
      "press_release": "Apple today announced financial results ...",
      "quarterly": { "revenue": 124300000000, "eps": 2.18, "...": "..." },
      "annual": { "...": "..." }
    }
  ]
}
```

The `signals` block carries the revenue and EPS surprise and the guidance direction. News and filings repeat these same numbers. See [Synthetic data](/concepts/synthetic-data#internal-consistency).

## Earnings calendar

```http theme={null}
GET /earnings/calendar
```

Upcoming/known earnings dates for a ticker.

| Parameter     | Type    | Required | Default | Description             |
| ------------- | ------- | -------- | ------- | ----------------------- |
| `scenario_id` | string  | Yes      | -       | The world to read from. |
| `ticker`      | string  | Yes      | -       | Ticker symbol to query. |
| `limit`       | integer | No       | 20      | Page size (max 100).    |
| `offset`      | integer | No       | 0       | Pagination offset.      |

<CodeGroup>
  ```bash cURL theme={null}
  curl -s "https://api.davidhf.com/earnings/calendar?scenario_id=<id>&ticker=AAPL" \
    -H "X-API-KEY: YOUR_API_KEY"
  ```

  ```python Python theme={null}
  dd.earnings.calendar("AAPL", scenario_id="<id>")
  ```
</CodeGroup>

```json theme={null}
{
  "earnings_calendar": [
    {
      "ticker": "AAPL",
      "report_period": "2026-03-31",
      "fiscal_period": "Q1",
      "earnings_date": "2026-04-24",
      "filing_datetime": "2026-04-24T16:30:00"
    }
  ]
}
```

## Discovery helper

```http theme={null}
GET /earnings/tickers
```

Takes only `scenario_id`; returns tickers with earnings.

```json theme={null}
{ "tickers": ["AAPL", "MSFT", "..."] }
```