Earnings Screener

Query reported earnings and estimates by reporting period for a single stock.

GET/api/v1/earnings/screener
Domain
Estimates & Earnings
Level
Asset
MCP tool
REST-only

Available data

Returns
Query reported earnings and estimates by reporting period for a single stock
What each request returns
Use schema_version=earnings_screener.v1 and entity_id or market-prefixed symbol. The verified example returns partial: inspect coverage and comparison_status; missing values are not zero. REST-only.

Authentication

Send Authorization: Bearer YOUR_API_KEY or X-API-KEY on every request.

Query Parameters

Contract version
schema_versionstringqueryrequired

Schema version; use earnings_screener.v1. · earnings_screener.v1

request_idstringqueryoptional

Request identifier

Company identification

Provide entity_id or a market-prefixed symbol, such as US.AAPL

entity_idstringqueryoptional

Entity identifier; provide entity_id or a market-prefixed symbol

symbolstringqueryExampleUS.AAPLoptional

Symbol with market prefix, e.g. US.AAPL; alternative to entity_id

marketstringqueryoptional

Equity market code. · us_equity / hk_equity / kr_equity

Reporting periods
period_typestringqueryoptional

Period type: quarterly, annual or both (all). · quarterly / annual / all · Default: quarterly

period_limitintegerqueryoptional

Maximum reporting periods; default 15, range 1–15. · ≥ 1, ≤ 15

Return options
include_actualbooleanqueryoptional

Include reported actual values. · Default: true

include_forecastbooleanqueryoptional

Include forecast values. · Default: true

Response

schema_versionstring

Schema version; use earnings_screener.v1

request_idstring

Request identifier

data_statusDataStatus

Data status

empty_reasonunknown | null

Reason for an empty result

marketMarket

Market code

entity_idstring

entity_id

available_period_types[]string[]

Available period types

available_metrics[]string[]

Available metrics

selected_period_typestring

Selected period type

latest_periodstring

Latest reporting period

period_countnumber

Returned period count

periods[]object[]

Reporting periods

period_keystring

Reporting period identifier

period_labelstring

Reporting period label

period_typestring

Period type: quarterly, annual or both (all)

fiscal_yearnumber

Fiscal year

fiscal_quarternumber

Fiscal quarter

report_datedatetime

Report date

report_statusstring

Report status

revenue_actualnumber

Reported revenue

revenue_estimatenumber

Estimated revenue

revenue_actual_yoynumber

Actual revenue year-over-year change (ratio)

revenue_estimate_yoynumber

Estimated revenue year-over-year change (ratio)

revenue_surprise_absnumber

Revenue minus estimate

revenue_surprise_pctnumber

Revenue surprise ratio

eps_actualnumber

Reported EPS

eps_estimatenumber

Estimated EPS

eps_actual_yoynumber

Actual EPS year-over-year change (ratio)

eps_estimate_yoynumber

Estimated EPS year-over-year change (ratio)

eps_surprise_absnumber

EPS minus estimate

eps_surprise_pctnumber

EPS surprise ratio

currencystring

Currency

eps_basisstring

EPS basis

announcement_cutoff_utcunknown | null

Announcement cutoff in UTC; null if unavailable

comparison_statusstring

Actual/estimate comparability

data_statusDataStatus

Data status

empty_reasonunknown | null

Reason for an empty result

summaryobject

Summary

period_keystring

Reporting period identifier

revenue_actualnumber

Reported revenue

eps_actualnumber

Reported EPS

revenue_surprise_pctnumber

Revenue surprise ratio

eps_surprise_pctnumber

EPS surprise ratio

coverageobject

Coverage and missing-data details

requested_period_limitnumber

requested_period_limit

available_period_countnumber

available_period_count

returned_period_countnumber

returned_period_count

history_insufficientboolean

history_insufficient

period_continuitystring

period_continuity

history_startstring

history_start

history_endstring

history_end

source_statusstring

source_status

source_refsobject

source_refs

source_tables[]string[]

source_tables

actual_ownerstring

actual_owner

generated_atdatetime

generated_at

Errors & fallback

200
assets_resolve name multi-match; confirm from data[] candidates.
200
The object resolved but no data is available; empty_reason may be not_covered_by_source, unsupported_metric, or limited_depth.
400
Invalid parameters or an ambiguous market listing; ambiguity responses include required_params + candidates.
401
The API key is missing or invalid.
403
The current key scope or plan cannot access this data domain.
404
The requested resource does not exist; source coverage gaps are not 404 responses.
402
Credits or monthly quota exhausted.
429
Request rate exceeded; retry_after is returned in the body and Retry-After in the response headers.