Get reported earnings
Summarize a company’s earnings in one row per period, with revenue, profit, EPS, cash flow and headline margins and growth.
How it works
-
Choose the right tool. For a line item such as operating expenses, use
get_financials. For a ratio trend such as return on equity, useget_financial_metrics. -
Choose the period type.
quarterly(the default),half_year,annual,ttmfor trailing twelve months, orreportedfor exactly what was filed. Five years of annual results isperiod=annual&limit=5. -
If you don't choose, you get what the company actually reports. US companies report quarters. Most UK and European companies don't, so you get half-years, or years if there are no half-years either. Tesco (
TSCO:LN) comes back annual. -
Some periods are arithmetic, and we show the arithmetic. Companies rarely file a standalone fourth quarter; they file the full year. So Q4 is the full year minus the first nine months, and
include_sources=trueshows the calculation with both filings. -
Converted figures keep their originals.
currency=USDconverts amounts and EPS at each period's average rate. Amounts without a usable rate are null. The figures as filed, in the currency they were filed in, are available inprovenancewhen you request sources. -
known_bygives you what was known at the time.known_by=2024-01-01uses only evidence available by that date. Later restatements stay out, which matters in a backtest: the market in 2023 didn't know about the 2024 restatement either. -
An empty answer tells you what does exist, and costs nothing. Ask for quarters from a company that reports only years and you get an empty list, a
messagesaying so, andavailable_periodslisting what it does report.
Request
GET /api/v1/earnings with your API key. AI assistants call it as the get_earnings tool, with the same parameters.
Parameters
qstringrequired
Ticker with its exchange code or MIC (AAPL:US, AAPL:XNAS, TSCO:XLON), ISIN, CUSIP, SEDOL, WKN, FIGI, LEI, CIK or company registration number. Any ticker and mic a listing returns work as ticker:mic.
More parameters
include_sourcesboolean
Include available source documents and supporting evidence. Omit for data only.
Default: false
periodstring
Period type. Default: quarterly, or what the company reports.
One of: quarterly, half_year, annual, ttm, reported
currencystring
Currency to convert amounts and EPS to, such as USD. Default: as reported.
fromdate
Only periods ending on or after this date.
YYYY-MM-DD
todate
Only periods ending on or before this date.
YYYY-MM-DD
known_bydate
Use evidence available on or before this date.
YYYY-MM-DD
available_ondate
Evidence available on this date.
YYYY-MM-DD
available_on_gtedate
Evidence available on or after this date.
YYYY-MM-DD
available_on_gtdate
Evidence available after this date.
YYYY-MM-DD
available_on_ltedate
Evidence available on or before this date.
YYYY-MM-DD
available_on_ltdate
Evidence available before this date.
YYYY-MM-DD
limitinteger
Periods to return.
Default: 20 · From 1 to 100
offsetinteger
Periods to skip. Use next_offset from the previous page.
Default: 0 · From 0 to 9007199254740991
Response
JSON with these fields. A field the source doesn't report is null or left out. When nothing matches, message says why and what to ask instead, and available_periods lists what the company has. Empty answers are free.
queryThe identifier asked for
earningsarray of objectsrequired
Show child attributes
start_dateFirst day of the period
end_dateLast day of the period
periodannual, quarterly, half_year, ttm or interim
fiscal_yearFiscal year of the period, when established
fiscal_periodFiscal period label, such as FY, Q1–Q4 or H1–H2
reporting_currencyCurrency the company reported in
currencyCurrency of the amounts and EPS in this response
currency_conversionobject
Show child attributes
fromCurrency converted from
rateRate applied
methodHow the rate was derived
rate_start_dateFirst day the rate covers
rate_end_dateLast day the rate covers
revenueRevenue
net_incomeProfit or loss attributable to shareholders of the parent: the figure EPS is based on
net_income_including_non_controlling_interestsConsolidated profit or loss, including the share of non-controlling interests
net_income_available_to_common_shareholdersProfit available to common shareholders
earnings_per_shareBasic EPS
earnings_per_share_dilutedDiluted EPS
weighted_average_sharesWeighted average shares, basic
weighted_average_shares_dilutedWeighted average shares, diluted
cost_of_revenueCost of revenue
gross_profitGross profit
operating_incomeOperating profit or loss
pretax_incomeProfit or loss before tax
income_tax_expenseIncome tax expense
ebitPretax income plus compatible interest expense; null when unavailable
net_cash_flow_from_operationsNet cash from operating activities for this exact period
net_cash_flow_from_investingNet cash from investing activities for this exact period
net_cash_flow_from_financingNet cash from financing activities for this exact period
capital_expenditureCash spent on property, plant and equipment, negative for an outflow
free_cash_flowOperating cash flow plus signed capital expenditure; missing inputs are not zero
gross_marginGross profit / revenue, as a decimal ratio; null for non-positive revenue
operating_marginOperating income / revenue, as a decimal ratio; null for non-positive revenue
net_marginNet income (attributable to the parent) / revenue, as a decimal ratio; null for non-positive revenue
net_margin_including_non_controlling_interestsConsolidated net income, including non-controlling interests, / revenue, as a decimal ratio; null for non-positive revenue
free_cash_flow_marginFree cash flow / revenue, as a decimal ratio; null for non-positive revenue
revenue_growthYear-over-year revenue growth as a decimal ratio in reporting currency; null for missing or non-positive base
earnings_growthYear-over-year parent-profit growth as a decimal ratio in reporting currency; null for missing or non-positive base
operating_income_growthYear-over-year operating-income growth as a decimal ratio in reporting currency; null for missing or non-positive base
earnings_per_share_growthYear-over-year basic EPS growth as a decimal ratio; null for an incompatible share basis or missing/non-positive base
free_cash_flow_growthYear-over-year free-cash-flow growth as a decimal ratio in reporting currency; null for missing or non-positive base
available_onLatest known availability date of evidence contributing to these figures, including comparisons
income_statement_available_onAvailability date of the underlying income statement
provenancearray of objects
Show child attributes
fieldResponse field explained by this evidence
valueValue in this response, after any currency conversion
derivationReported, or the method used to derive the figure; null when unknown
inputsarray of objects
Show child attributes
fieldInput metric for a ratio or growth calculation; numerator/current first, denominator/prior second
valueInput value in reporting currency
start_dateInput period start
end_dateInput period end
currencyInput reporting currency
sourcesarray of objects
Show child attributes
document_idFiling directory key when available
source_document_idOriginal source identifier, such as an SEC accession
formFiling form or document type
filing_dateDate this source filing was published
urlDirect source filing URL; null when no document URL is available
conceptReported concept or source line label used to locate the figure
valueOriginal reported value as a string, before output currency conversion
unitOriginal unit, including currency or currency per share
start_dateOriginal reported period start
end_dateOriginal reported period end
next_offsetoffset of the next page, null on the last
matchIdentifier lookup outcome. A found match can still have an empty page.
messageOnly when no periods match: why, and what to ask instead
available_periodsarray of objects
Show child attributes
periodOnly when no periods match: a period type the company has (quarterly, half_year, annual, ttm)
countPeriods of that type
earliest_end_dateEnd of the earliest
latest_end_dateEnd of the latest
Errors
| Status | Meaning |
|---|---|
| 400 | Missing, unknown or invalid parameter, or an identifier that can't be looked up |
| 401 | Missing, unknown or revoked API key |
| 402 | No active plan or trial, or the included request allowance is used |
| 403 | API access of the account is suspended |
| 404 | The identifier matches nothing or is ambiguous. The match field identifies the outcome |
| 429 | Over the plan's rate limit; Retry-After says when to retry |
| 500 | Internal error; the same request is unlikely to succeed on retry |
| 503 | The data couldn't be loaded right now; Retry-After says when to retry, when known |
Errors are JSON with an error message saying what to fix. Errors are free. See Errors and limits.