# stocks_get_earnings_dates One company's earnings-announcement history and estimated next window. | Field | Value | | --- | --- | | Category | Stocks (`stocks`) | | Exposure | public | | MCP tool | `stocks_get_earnings_dates` | | Documentation | https://www.agentdatasets.com/docs/tools/stocks_get_earnings_dates | ## Description 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)`. ## Parameters Input schema advertised to MCP clients and mirrored by the REST query string. | Parameter | In | Type | Required | Default | Constraints | Description | | --- | --- | --- | --- | --- | --- | --- | | ticker_or_cik | input | `string` | yes | — | — | The company: a ticker symbol (AAPL, BRK.B) or a CIK (320193 or 0000320193). | | limit | input | `integer` | no | 8 | min 1, max 40 | Announcement-history rows to return newest first; default 8, max 40. Values outside 1-40 are rejected, never clamped. | ## Provenance - `sec-edgar-submissions` — U.S. Securities and Exchange Commission (EDGAR), Filing metadata only — form type, filing date, period of report, accession number, item codes — plus links to source documents on sec.gov; this connector never fetches or stores document contents (section extraction is `sec-edgar-archives`) (U.S. Government work, public domain (17 U.S.C. § 105)). See https://www.agentdatasets.com/docs/attribution.md Dataset registry: `stocks_company_events`.