stocks_get_earnings_dates

One company's earnings-announcement history and estimated next window.

Use this for a compact answer to "when did this company announce earnings, and when might it announce next?" Use stocks_get_company_events(category="results_announcement") for deeper cursor-paged announcement history or the broader 8-K event timeline. Use stocks_get_expected_report when the question is about the next periodic SEC filing rather than an earnings announcement.

These are estimates, not schedules. This platform ingests no forward earnings calendar, so it has no confirmed-date state and uses no confirmed vocabulary. data.next is first derived from the company's own non-amendment announcement cadence and labeled derived-from-announcement-cadence. If there are fewer than two usable announcement gaps, an active filing estimate may be used instead and is explicitly labeled derived-from-filing-cadence; the bases are never mixed. Stale or passed announcement arithmetic remains visible with an explanatory reason, while no usable basis returns data.next: null and a data.reason naming both gaps.

The shared envelope's data echoes ticker, cik, and company_name, then provides history, next, and reason. Each history row carries announced_on, filed_on, form_type, accession_number, SEC document links, source, and as_of. Amendments remain visible in history but never feed the estimate. next carries an inclusive window_start/window_end, basis, cadence, observation count, announcement median_gap_days (null for the filing fallback), stale flag, reason, source, and as-of timestamp. meta.source is sec-edgar-submissions; pagination is null.

History is bounded newest-first: default 8 rows, max 40, with out-of-range values rejected rather than clamped. For deeper history, call stocks_get_company_events(category="results_announcement") and page with its pagination.next_cursor.

Errors carry a machine code: unknown_entity for an unknown ticker or CIK (ticker typos include did-you-mean suggestions), and bad_parameter for an out-of-range limit.

Example: stocks_get_earnings_dates(ticker_or_cik="AAPL", limit=8).