Earnings
Upcoming and historical earnings announcements, actuals, estimates and surprises. The sources give the release date and session, not the instant, so report_at is always null. report_date is the source's release date, except where the source dates a reported quarter on or before its period end or with a later quarter's date: it is then the date of the company's first Form 8-K under Item 2.02 (results of operations) within 100 days after period_end, or null where there is none. Where report_date is null, from, to and ordering use period_end. eps_surprise and eps_surprise_ratio are the source's surprise and surprise percentage, the latter as a ratio. Revenue, fiscal year and fiscal quarter come from the company's statements and consensus for the same quarter, so an event known only from the earnings calendar carries none of them; period_start is not available. Default order: report_date descending (newest first), id ascending. Omitting entity selectors returns the entitled universe; explicit unauthorized selectors return 403. Data is delivered from validated canonical batches; a connected dataset with nothing published for the key's markets yet returns 503. Access requires the operation capability on the API key.
/v1/earnings- Required capability
- earnings.read
- Data timing
- As published by the source
- Credits
- 5 credits per request.
Parameters
company_idsstringoptional · query- Filter by issuer IDs. May be combined with instrument selectors; filters intersect, except on issuer-level datasets (statements, segments, estimates, earnings, insider transactions), where an instrument selector is read as its company and takes the place of company_ids, so results cover every share class.
instrument_idsstringoptional · query- Filter by stable instrument IDs. IDs and symbols may not be combined.
symbolsstringoptional · query- Convenience lookup for exchange-listed instruments as MIC:TICKER or a bare ticker, which resolves to the exchange listing that ticker; resolves at symbol_at. The MIC and the ticker are case-insensitive, and two spellings of one listing (AAPL and XNAS:AAPL) count as a repeated value. A bare ticker that names no listing as written is also read in the common vendor spellings: with an exchange suffix (RY.TO, SHEL.L, VOD.LSE, BHP.AX), ^GSPC for INDEX:GSPC, and EURUSD=X or EURUSD for FOREX:EUR-USD. A ticker may contain a space (BAC PRL) but not start or end with one. A request in which no symbol resolves returns 404 symbol-not-resolved; otherwise each symbol that does not resolve, or resolves to a listing with no rows for the request (no-data), is an entry of meta.errors. IDs and symbols may not be combined.
symbol_atstringoptional · query- Resolve symbols as they were assigned at the end of this UTC date (YYYY-MM-DD); defaults to as_of. Only listings the security master holds resolve: it was built in September 2026 and records delistings from then on, so most issuers delisted earlier, such as TWTR or SIVB, resolve at no date. Only valid with symbols.
fromstringoptional · query- Inclusive lower bound on report_date.
tostringoptional · query- Inclusive upper bound on report_date; must be on or after from, so from equal to to selects one day.
statusstringoptional · query- Announcement status: estimated (results not yet reported) or reported. The connected source reports neither confirmed nor cancelled announcements, so those match nothing.
estimatedconfirmedreportedcancelled as_ofstringoptional · query- Knowledge cutoff as a UTC date (YYYY-MM-DD): the response reflects what was known by the end of that day. Defaults to now; cannot be in the future. A date from before the dataset's knowledge history returns 422 point-in-time-unavailable naming the earliest one, which GET /v1/datasets lists as earliest_as_of.
known_fromstringoptional · query- First UTC date (YYYY-MM-DD, inclusive) on which a revision became known.
known_tostringoptional · query- Last UTC date (YYYY-MM-DD, inclusive) on which a revision became known; on or after known_from.
orderstringoptional · query- Direction on report_date; ties use ID ascending.
Default:ascdescdesc limitintegeroptional · query- Maximum records per page.Default:
100 cursorstringoptional · query- Opaque cursor, expires after one hour; binds filters, order, resolved as_of, account/key and entitlement. Repeat the original query unchanged.
formatstringoptional · query- Response format. csv returns the data rows with a header row, for spreadsheet functions such as IMPORTDATA; nested fields become dotted columns and lists one JSON array cell, the next page cursor is returned in X-Next-Cursor and meta.errors in X-Meta-Errors. A result without rows is the header row alone, listing the documented fields of a row. Default json, or csv when format is omitted and the Accept header ranks text/csv above JSON; a format the Accept header does not admit returns 406 not-acceptable.
jsoncsv
Response fields
Returns data as an array of records. All example values are illustrative.
idstring- Record identifier, stable across revisions.
company_idstring- Opaque stable public identifier; never an internal database key.
instrumentsarray- instruments
period_startstring · null- First day of the fiscal period. The connected source does not establish it: always null.
period_endstring- period end
fiscal_yearinteger · null- Fiscal year the quarter belongs to, named by the calendar year in which that fiscal year ends (fiscal 2026 ends 2026-09-30, or 2026-01-31); an issuer that names a year ending in January or February after the year it began in calls it one less. Derived from the fiscal year ends of the company's annual statements; null when they do not place the quarter.
fiscal_quarterinteger · null- Quarter of the fiscal year, 1 to 4, from the analyst consensus for the quarter or the company's annual statements; null when neither places the quarter.
periodstring · null- quarterly when the company's statements or consensus describe the quarter; null for an event known only from the earnings calendar.
quarterlyannual report_datestring · null- Date the results were released; null when the release date is unknown, and the event is then timed by period_end.
report_atstring · null- Instant the results were released. The connected sources give the release date and session (report_date and timing), not the instant: always null. A company's Form 8-K is accepted minutes to hours after its release, so its acceptance time is not substituted.
timingstring- Time relative to the primary listing's session: before_market, after_market or unknown; the connected source reports no during_market releases.
before_marketduring_marketafter_marketunknown statusstring- Event status: reported once the source gives the quarter's actual EPS, estimated before that. The connected source reports neither confirmed nor cancelled announcements, so those values never occur.
estimatedconfirmedreportedcancelled eps_actualobject- eps actual
eps_estimateobject- eps estimate
eps_surpriseobject- eps surprise
eps_surprise_ratiostring · null- Dimensionless ratio; 0.05 means 5%.
revenue_actualobject- Revenue of the quarter from the company's quarterly income statement, once reported; null when no statement for the quarter is held.
revenue_estimateobject- Analyst consensus revenue for the quarter. The consensus history begins in 2017; null for earlier quarters and for events known only from the earnings calendar.
Response metadata
Responses include meta.timezone. Dataset responses include next_cursor; health and exports have their own metadata. Request tracing uses the X-Request-ID header.
When something goes wrong
An empty data: [] is a successful query with no matching records. Invalid symbols, permissions and malformed parameters produce an RFC 9457 problem with an actionable detail.
Plans
Requires earnings.read. Access, recency and history depth come from the plan definitions the API enforces.
| Plan | Access | Recency | History |
|---|---|---|---|
| Free | Included | As published | 5 years |
| Developer | Included | As published | 5 years |
| Pro | Included | As published | 15 years |
| Commercial | Included | As published | Full history |
| Scale | Included | As published | Full history |
Free requests are limited to AAPL, NVDA, JNJ, PEP, MSFT, SPY, QQQ.
History is how far back a plan may request. How far records actually go for a symbol is history_from in dataset coverage. Nothing is real-time. Compare plans