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_marginoperating_marginnet_margin_including_non_controlling_interestsnet_marginreturn_on_equityreturn_on_assetsreturn_on_invested_capitalasset_turnoverinventory_turnoverreceivables_turnoverdays_sales_outstandingdays_inventory_outstandingoperating_cycleworking_capital_turnovercurrent_ratioquick_ratiocash_ratiooperating_cash_flow_ratiodebt_to_equitydebt_to_assetsinterest_coveragefree_cash_flow_marginpayout_ratiorevenue_growthearnings_growthoperating_income_growthebitda_growthearnings_per_share_growthfree_cash_flow_growthbook_value_growthearnings_per_sharebook_value_per_sharefree_cash_flow_per_share
-
Compare like periods. Use annual results for year-to-year trends or
ttmfor 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_byto limit calculations to evidence available by that date. Each row’savailable_onincludes 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_financialsfor 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.
queryRequested identifier
next_offsetOffset of the next page, or null
financial_metricsarray of objectsrequired
Show child attributes
available_onLatest known availability date of the evidence used to calculate this row
start_dateFirst day of the period
end_dateLast day of the period
periodReporting period type
fiscal_yearFiscal year
fiscal_periodEnding fiscal period label
reporting_currencyOriginal currency
currencyCurrency of monetary amounts per share
currency_conversionobject
Show child attributes
fromOriginal currency
period_average_rateAverage rate for period flows
closing_rateClosing rate for book value
closing_rate_dateDate of the closing rate
gross_marginGross profit divided by revenue.
operating_marginOperating income divided by revenue.
net_margin_including_non_controlling_interestsConsolidated net income divided by revenue.
net_marginProfit attributable to the parent divided by revenue.
return_on_equityParent profit divided by average opening and closing parent equity; not annualized.
return_on_assetsConsolidated profit divided by average opening and closing assets; not annualized.
return_on_invested_capitalOperating 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_turnoverRevenue divided by average assets over this period.
inventory_turnoverCost of revenue divided by average inventory over this period.
receivables_turnoverRevenue divided by average trade receivables; broad receivables are not substituted.
days_sales_outstandingActual days in the period divided by receivables turnover.
days_inventory_outstandingActual days in the period divided by inventory turnover.
operating_cycleDays sales outstanding plus days inventory outstanding.
working_capital_turnoverRevenue divided by average current assets less current liabilities.
current_ratioClosing current assets divided by current liabilities.
quick_ratioClosing cash, current investments and trade receivables divided by current liabilities; every component must be known.
cash_ratioClosing cash and cash equivalents divided by current liabilities.
operating_cash_flow_ratioOperating cash flow divided by closing current liabilities; not annualized.
debt_to_equityClosing total debt divided by total equity.
debt_to_assetsClosing total debt divided by total assets.
interest_coverageEBIT divided by interest expense.
free_cash_flow_marginOperating cash flow less gross PPE cash expenditure, divided by revenue; not issuer-adjusted free cash flow. Often unsuitable for financial institutions.
payout_ratioDeclared dividends per common share divided by basic earnings per share.
revenue_growthRevenue growth against the comparable year-earlier period; a non-positive base returns null.
earnings_growthParent-profit growth against the comparable year-earlier period; a non-positive base returns null.
operating_income_growthOperating-income growth against the comparable year-earlier period; a non-positive base returns null.
ebitda_growthGrowth 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_growthBasic earnings-per-share growth against the comparable year-earlier period; a non-positive base returns null.
free_cash_flow_growthFree-cash-flow growth against the comparable year-earlier period; a non-positive base returns null.
book_value_growthParent-equity growth against the comparable year-earlier period; a non-positive base returns null.
earnings_per_shareReported basic earnings per share.
book_value_per_shareClosing parent equity divided by closing common shares outstanding.
free_cash_flow_per_sharePeriod free cash flow divided by basic weighted-average common shares.
matchIdentifier 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.