Skip to content

Get historical financial metrics

Compare accounting ratios and per-share figures across periods, including operating margin, return on equity, current ratio and debt to equity.

How it works

Available metrics33 fields

Each row returns these metrics when available. See the response fields for definitions.

  • gross_margin
  • operating_margin
  • net_margin_including_non_controlling_interests
  • net_margin
  • return_on_equity
  • return_on_assets
  • return_on_invested_capital
  • asset_turnover
  • inventory_turnover
  • receivables_turnover
  • days_sales_outstanding
  • days_inventory_outstanding
  • operating_cycle
  • working_capital_turnover
  • current_ratio
  • quick_ratio
  • cash_ratio
  • operating_cash_flow_ratio
  • debt_to_equity
  • debt_to_assets
  • interest_coverage
  • free_cash_flow_margin
  • payout_ratio
  • revenue_growth
  • earnings_growth
  • operating_income_growth
  • ebitda_growth
  • earnings_per_share_growth
  • free_cash_flow_growth
  • book_value_growth
  • earnings_per_share
  • book_value_per_share
  • free_cash_flow_per_share
  • Compare like periods. Use annual results for year-to-year trends or ttm for trailing twelve months. Returns and turnover cover the selected period. Growth compares with the corresponding period a year earlier.
  • Read the units. A margin of 0.25 means 25%. A current ratio of 2 means current assets are twice current liabilities. Currency conversion applies only to monetary amounts per share.
  • Check what was known. Set known_by to limit calculations to evidence available by that date. Each row’s available_on includes the evidence used for comparisons. A null metric means the calculation lacks compatible inputs, a usable denominator or a required exchange rate.
  • Use statement data to check a ratio. Request the matching period from get_financials for its figures and optional filing links. The metrics series uses financial statements and covers accounting ratios rather than market-price multiples.

Request

GET /api/v1/financial-metrics with your API key. AI assistants call it as the get_financial_metrics 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: annual.

Default: annual · One of: annual, quarterly, half_year, ttm, reported

currencystring

Currency for per-share amounts, 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

Maximum number of metric rows.

Default: 20 · From 1 to 100

offsetinteger

Metric rows to skip.

Default: 0 · From 0 to 9007199254740991

Response

JSON with these fields. A field the source doesn't report is null or left out.

query

Requested identifier

next_offset

Offset of the next page, or null

financial_metricsarray of objectsrequired
Show child attributes
available_on

Latest known availability date of the evidence used to calculate this row

start_date

First day of the period

end_date

Last day of the period

period

Reporting period type

fiscal_year

Fiscal year

fiscal_period

Ending fiscal period label

reporting_currency

Original currency

currency

Currency of monetary amounts per share

currency_conversionobject
Show child attributes
from

Original currency

period_average_rate

Average rate for period flows

closing_rate

Closing rate for book value

closing_rate_date

Date of the closing rate

gross_margin

Gross profit divided by revenue.

operating_margin

Operating income divided by revenue.

net_margin_including_non_controlling_interests

Consolidated net income divided by revenue.

net_margin

Profit attributable to the parent divided by revenue.

return_on_equity

Parent profit divided by average opening and closing parent equity; not annualized.

return_on_assets

Consolidated profit divided by average opening and closing assets; not annualized.

return_on_invested_capital

Operating income after applying the effective tax rate (income tax expense divided by positive pretax income), divided by average opening and closing invested capital (total debt plus total equity less cash and equivalents). Tax rates outside 0–100% and non-positive average capital return null. The return covers the selected period.

asset_turnover

Revenue divided by average assets over this period.

inventory_turnover

Cost of revenue divided by average inventory over this period.

receivables_turnover

Revenue divided by average trade receivables; broad receivables are not substituted.

days_sales_outstanding

Actual days in the period divided by receivables turnover.

days_inventory_outstanding

Actual days in the period divided by inventory turnover.

operating_cycle

Days sales outstanding plus days inventory outstanding.

working_capital_turnover

Revenue divided by average current assets less current liabilities.

current_ratio

Closing current assets divided by current liabilities.

quick_ratio

Closing cash, current investments and trade receivables divided by current liabilities; every component must be known.

cash_ratio

Closing cash and cash equivalents divided by current liabilities.

operating_cash_flow_ratio

Operating cash flow divided by closing current liabilities; not annualized.

debt_to_equity

Closing total debt divided by total equity.

debt_to_assets

Closing total debt divided by total assets.

interest_coverage

EBIT divided by interest expense.

free_cash_flow_margin

Operating cash flow less gross PPE cash expenditure, divided by revenue; not issuer-adjusted free cash flow. Often unsuitable for financial institutions.

payout_ratio

Declared dividends per common share divided by basic earnings per share.

revenue_growth

Revenue growth against the comparable year-earlier period; a non-positive base returns null.

earnings_growth

Parent-profit growth against the comparable year-earlier period; a non-positive base returns null.

operating_income_growth

Operating-income growth against the comparable year-earlier period; a non-positive base returns null.

ebitda_growth

Growth in EBIT plus depreciation and amortization against the comparable year-earlier period. Missing or incompatible inputs and a non-positive base return null.

earnings_per_share_growth

Basic earnings-per-share growth against the comparable year-earlier period; a non-positive base returns null.

free_cash_flow_growth

Free-cash-flow growth against the comparable year-earlier period; a non-positive base returns null.

book_value_growth

Parent-equity growth against the comparable year-earlier period; a non-positive base returns null.

earnings_per_share

Reported basic earnings per share.

book_value_per_share

Closing parent equity divided by closing common shares outstanding.

free_cash_flow_per_share

Period free cash flow divided by basic weighted-average common shares.

match

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

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