Skip to content

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, use get_financial_metrics.
  • Choose the period type. quarterly (the default), half_year, annual, ttm for trailing twelve months, or reported for exactly what was filed. Five years of annual results is period=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=true shows the calculation with both filings.
  • Converted figures keep their originals. currency=USD converts 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 in provenance when you request sources.
  • known_by gives you what was known at the time. known_by=2024-01-01 uses 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 message saying so, and available_periods listing 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.

query

The identifier asked for

earningsarray of objectsrequired
Show child attributes
start_date

First day of the period

end_date

Last day of the period

period

annual, quarterly, half_year, ttm or interim

fiscal_year

Fiscal year of the period, when established

fiscal_period

Fiscal period label, such as FY, Q1–Q4 or H1–H2

reporting_currency

Currency the company reported in

currency

Currency of the amounts and EPS in this response

currency_conversionobject
Show child attributes
from

Currency converted from

rate

Rate applied

method

How the rate was derived

rate_start_date

First day the rate covers

rate_end_date

Last day the rate covers

revenue

Revenue

net_income

Profit or loss attributable to shareholders of the parent: the figure EPS is based on

net_income_including_non_controlling_interests

Consolidated profit or loss, including the share of non-controlling interests

net_income_available_to_common_shareholders

Profit available to common shareholders

earnings_per_share

Basic EPS

earnings_per_share_diluted

Diluted EPS

weighted_average_shares

Weighted average shares, basic

weighted_average_shares_diluted

Weighted average shares, diluted

cost_of_revenue

Cost of revenue

gross_profit

Gross profit

operating_income

Operating profit or loss

pretax_income

Profit or loss before tax

income_tax_expense

Income tax expense

ebit

Pretax income plus compatible interest expense; null when unavailable

net_cash_flow_from_operations

Net cash from operating activities for this exact period

net_cash_flow_from_investing

Net cash from investing activities for this exact period

net_cash_flow_from_financing

Net cash from financing activities for this exact period

capital_expenditure

Cash spent on property, plant and equipment, negative for an outflow

free_cash_flow

Operating cash flow plus signed capital expenditure; missing inputs are not zero

gross_margin

Gross profit / revenue, as a decimal ratio; null for non-positive revenue

operating_margin

Operating income / revenue, as a decimal ratio; null for non-positive revenue

net_margin

Net income (attributable to the parent) / revenue, as a decimal ratio; null for non-positive revenue

net_margin_including_non_controlling_interests

Consolidated net income, including non-controlling interests, / revenue, as a decimal ratio; null for non-positive revenue

free_cash_flow_margin

Free cash flow / revenue, as a decimal ratio; null for non-positive revenue

revenue_growth

Year-over-year revenue growth as a decimal ratio in reporting currency; null for missing or non-positive base

earnings_growth

Year-over-year parent-profit growth as a decimal ratio in reporting currency; null for missing or non-positive base

operating_income_growth

Year-over-year operating-income growth as a decimal ratio in reporting currency; null for missing or non-positive base

earnings_per_share_growth

Year-over-year basic EPS growth as a decimal ratio; null for an incompatible share basis or missing/non-positive base

free_cash_flow_growth

Year-over-year free-cash-flow growth as a decimal ratio in reporting currency; null for missing or non-positive base

available_on

Latest known availability date of evidence contributing to these figures, including comparisons

income_statement_available_on

Availability date of the underlying income statement

provenancearray of objects
Show child attributes
field

Response field explained by this evidence

value

Value in this response, after any currency conversion

derivation

Reported, or the method used to derive the figure; null when unknown

inputsarray of objects
Show child attributes
field

Input metric for a ratio or growth calculation; numerator/current first, denominator/prior second

value

Input value in reporting currency

start_date

Input period start

end_date

Input period end

currency

Input reporting currency

sourcesarray of objects
Show child attributes
document_id

Filing directory key when available

source_document_id

Original source identifier, such as an SEC accession

form

Filing form or document type

filing_date

Date this source filing was published

url

Direct source filing URL; null when no document URL is available

concept

Reported concept or source line label used to locate the figure

value

Original reported value as a string, before output currency conversion

unit

Original unit, including currency or currency per share

start_date

Original reported period start

end_date

Original reported period end

next_offset

offset of the next page, null on the last

match

Identifier lookup outcome. A found match can still have an empty page.

message

Only when no periods match: why, and what to ask instead

available_periodsarray of objects
Show child attributes
period

Only when no periods match: a period type the company has (quarterly, half_year, annual, ttm)

count

Periods of that type

earliest_end_date

End of the earliest

latest_end_date

End 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.

Esc

Documentation

Make your first request API keys and authentication Errors and limits Connect an AI assistant (MCP) Usage and billing Contact support Get company profile Get securities and listings Get reported earnings Get financial statements Get historical financial metrics Get financial segments Get historical shares outstanding Get fund holdings Find funds holding a security Screen companies Get screener filters
↑↓ to move to open