# GET /v2/events?kind=earnings

**Earnings**

Quarterly earnings reports, one event per report, timestamped at the date the results were announced.

## Query / path parameters

| Name | In | Type | Required | Description |
|------|----|----|----------|-------------|
| `kind` | query | string | yes | Fix to `earnings` for this view (comma-combine kinds to merge timelines). Example: `earnings`. |
| `ticker` | query | string | no | Single symbol. Beats `tickers` when both are passed. Example: `NVDA`. |
| `tickers` | query | string[] | no | Comma-separated symbols, up to 50. Not combinable with `universe`; `ticker` wins when both are passed. Example: `AAPL,MSFT`. |
| `universe` | query | string | no | System or caller-owned universe slug. Example: `top_100`. |
| `from` | query | string | no | `YYYY-MM-DD` or ISO timestamp (inclusive). `since` is accepted as an alias. Example: `2026-08-19`. |
| `to` | query | string | no | `YYYY-MM-DD` or ISO timestamp — a bare `YYYY-MM-DD` means through the end of that day; timestamps are exclusive. `until` is accepted as an alias. Example: `2026-06-02`. |
| `q` | query | string | no | SQL filter. This kind's payload fields are first-class typed columns here: `reported_eps`, `estimated_eps`, `surprise`, `surprise_pct` (numeric), `fiscal_period_end` (date), `report_time` (text) — e.g. `surprise_pct > 10`. `payload->>'…'` works too. Base columns: `ticker`, `ts`, `kind`, `payload`. Example: `surprise_pct > 10`. |
| `limit` | query | integer | no | Rows per page. Max 1000. Default: `50`. Example: `5`. |
| `cursor` | query | string | no | Opaque cursor from the previous response. |

## Returns

- `as_of` (string) — Server time this response was assembled (ISO 8601).
- `query` (object) — Your filters, echoed.
- `count` (number) — Rows in this page.
- `next_cursor` (string) — Opaque token for the next page; `null` on the last page. Pass it back as `cursor`.
- `results` (array) — One row per event, newest first.
  - `ticker` (string) — Symbol that reported.
  - `ts` (string) — Report date as an ISO timestamp — the event's timeline position.
  - `kind` (string) — Always `earnings` on this view.
  - `payload` (object) — The report.
    - `fiscal_period_end` (string) — Last day of the fiscal quarter the report covers (`YYYY-MM-DD`).
    - `reported_eps` (number, optional) — EPS as reported. `null` when the company hasn't disclosed a comparable figure.
    - `estimated_eps` (number, optional) — Consensus estimate going in; `null` for uncovered names.
    - `surprise` (number, optional) — reported − estimated, as the vendor computed it (stored, not re-derived).
    - `surprise_pct` (number, optional) — The surprise as a percentage of the estimate; `null` when there was no estimate.
    - `report_time` (string, optional) — When in the session the report landed — `pre-market` or `post-market`.

## Sample response

```json
{
  "as_of": "2026-08-31T20:30:26.000Z",
  "query": { "kind": "earnings", "universe": "top_100", "since": "2026-08-19T00:00:00.000Z", "limit": 50 },
  "count": 1,
  "next_cursor": null,
  "results": [
    { "ticker": "HAFN", "ts": "2026-08-28T00:00:00.000Z", "kind": "earnings",
      "payload": { "fiscal_period_end": "2026-06-30", "reported_eps": 0.56,
                   "estimated_eps": 0.51, "surprise": 0.05, "surprise_pct": 9.8039,
                   "report_time": "pre-market" } }
  ]
}
```

## More examples

### One ticker's report history

Request:

```shell
curl "https://api.tickerbot.io/v2/events?kind=earnings&ticker=NVDA&from=2026-01-23" \
  -H "Authorization: Bearer YOUR_KEY"
```

Response (`200`):

```json
// Same envelope — NVDA's reports, newest first.
```

## Notes

- This is [`GET /v2/events`](/docs/endpoints/events/all) with `kind=earnings`; it has its own page because the payload is its own contract. The full query grammar (`q`, `group_by`/`select`/`having`, `join=state`, cursor rules) lives there and applies here unchanged.
- Reports only, not a calendar: events land when results are announced (timestamped at the report date), so there are no future-dated rows. `surprise` and `surprise_pct` are the vendor's own arithmetic, stored as published — they are not recomputed from the two EPS fields. `reported_eps`/`estimated_eps` are `null` where no comparable figure or estimate exists; `fiscal_period_end` dates the quarter the report covers. Latency: daily, via the evening ET ingestion pipeline.
- To be pushed instead of polling, create an event-trigger webhook: [`POST /v2/webhooks`](/docs/endpoints/webhooks/create) with `trigger.kinds=earnings`.
- For fundamentals as *state* — EPS and statement columns on an aligned quarterly grid rather than report events — use [`GET /v2/series`](/docs/endpoints/series) at `interval=1q`.

---

Interactive sandbox + parameter editor: https://tickerbot.io/docs/endpoints/events/earnings