View as markdown
Endpoints › Events

Earnings

GEThttps://api.tickerbot.io/v2/events?kind=earnings

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

Query parameters

stringrequiredfixed by this page

Fix to earnings for this view (comma-combine kinds to merge timelines).

string

Single symbol. Beats tickers when both are passed.

string[]

Comma-separated symbols, up to 50. Not combinable with universe; ticker wins when both are passed.

string

System or caller-owned universe slug.

string

YYYY-MM-DD or ISO timestamp (inclusive). since is accepted as an alias.

string

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.

string

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. See the signals catalog for columns + flags you can compose.

integerdefault 50

Rows per page. Max 1000.

string

Opaque cursor from the previous response.

Returns

as_ofstring

Server time this response was assembled (ISO 8601).

queryobject

Your filters, echoed.

countnumber

Rows in this page.

next_cursorstring

Opaque token for the next page; `null` on the last page. Pass it back as `cursor`.

resultsarray

One row per event, newest first.

tickerstring

Symbol that reported.

tsstring

Report date as an ISO timestamp — the event's timeline position.

kindstring

Always `earnings` on this view.

payloadobject

The report.

fiscal_period_endstring

Last day of the fiscal quarter the report covers (`YYYY-MM-DD`).

reported_epsnumberoptional

EPS as reported. `null` when the company hasn't disclosed a comparable figure.

estimated_epsnumberoptional

Consensus estimate going in; `null` for uncovered names.

surprisenumberoptional

reported − estimated, as the vendor computed it (stored, not re-derived).

surprise_pctnumberoptional

The surprise as a percentage of the estimate; `null` when there was no estimate.

report_timestringoptional

When in the session the report landed — `pre-market` or `post-market`.

Notes

  • This is GET /v2/events 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 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 at interval=1q.

More examples

One ticker's report history
curl "https://api.tickerbot.io/v2/events?kind=earnings&ticker=NVDA&from=2026-01-23" \
  -H "Authorization: Bearer YOUR_KEY"
Response
// Same envelope — NVDA's reports, newest first.