# 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 {#how-it-works} - **Available metrics.** Each row returns the following metrics when available: 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 {#request} `GET /api/v1/financial-metrics` with your API key. AI assistants call it as the `get_financial_metrics` tool, with the same parameters. ``` curl "https://financialdb.ai/api/v1/financial-metrics?q=AAPL:US" \ -H "Authorization: Bearer $FDB_API_KEY" ``` ## Parameters {#parameters} | Parameter | Type | Description | |---|---|---| | `include_sources` | boolean | Include available source documents and supporting evidence. Omit for data only. Default: `false`. | | `q` (required) | string | 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. | | `period` | string: annual, quarterly, half_year, ttm, reported | Period type. Default: annual. Default: `annual`. | | `currency` | string | Currency for per-share amounts, such as USD. Default: as reported. | | `from` | date | Only periods ending on or after this date. | | `to` | date | Only periods ending on or before this date. | | `known_by` | date | Use evidence available on or before this date. | | `available_on` | date | Evidence available on this date. | | `available_on_gte` | date | Evidence available on or after this date. | | `available_on_gt` | date | Evidence available after this date. | | `available_on_lte` | date | Evidence available on or before this date. | | `available_on_lt` | date | Evidence available before this date. | | `limit` | integer: 1–100 | Maximum number of metric rows. Default: `20`. | | `offset` | integer: 0–9007199254740991 | Metric rows to skip. Default: `0`. | ## Response {#response} JSON with these fields. A field the source doesn't report is null or left out. | Field | Description | |---|---| | `query` | Requested identifier | | `next_offset` | Offset of the next page, or null | | `financial_metrics[].available_on` | Latest known availability date of the evidence used to calculate this row | | `financial_metrics[].start_date` | First day of the period | | `financial_metrics[].end_date` | Last day of the period | | `financial_metrics[].period` | Reporting period type | | `financial_metrics[].fiscal_year` | Fiscal year | | `financial_metrics[].fiscal_period` | Ending fiscal period label | | `financial_metrics[].reporting_currency` | Original currency | | `financial_metrics[].currency` | Currency of monetary amounts per share | | `financial_metrics[].currency_conversion.from` | Original currency | | `financial_metrics[].currency_conversion.period_average_rate` | Average rate for period flows | | `financial_metrics[].currency_conversion.closing_rate` | Closing rate for book value | | `financial_metrics[].currency_conversion.closing_rate_date` | Date of the closing rate | | `financial_metrics[].gross_margin` | Gross profit divided by revenue. | | `financial_metrics[].operating_margin` | Operating income divided by revenue. | | `financial_metrics[].net_margin_including_non_controlling_interests` | Consolidated net income divided by revenue. | | `financial_metrics[].net_margin` | Profit attributable to the parent divided by revenue. | | `financial_metrics[].return_on_equity` | Parent profit divided by average opening and closing parent equity; not annualized. | | `financial_metrics[].return_on_assets` | Consolidated profit divided by average opening and closing assets; not annualized. | | `financial_metrics[].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. | | `financial_metrics[].asset_turnover` | Revenue divided by average assets over this period. | | `financial_metrics[].inventory_turnover` | Cost of revenue divided by average inventory over this period. | | `financial_metrics[].receivables_turnover` | Revenue divided by average trade receivables; broad receivables are not substituted. | | `financial_metrics[].days_sales_outstanding` | Actual days in the period divided by receivables turnover. | | `financial_metrics[].days_inventory_outstanding` | Actual days in the period divided by inventory turnover. | | `financial_metrics[].operating_cycle` | Days sales outstanding plus days inventory outstanding. | | `financial_metrics[].working_capital_turnover` | Revenue divided by average current assets less current liabilities. | | `financial_metrics[].current_ratio` | Closing current assets divided by current liabilities. | | `financial_metrics[].quick_ratio` | Closing cash, current investments and trade receivables divided by current liabilities; every component must be known. | | `financial_metrics[].cash_ratio` | Closing cash and cash equivalents divided by current liabilities. | | `financial_metrics[].operating_cash_flow_ratio` | Operating cash flow divided by closing current liabilities; not annualized. | | `financial_metrics[].debt_to_equity` | Closing total debt divided by total equity. | | `financial_metrics[].debt_to_assets` | Closing total debt divided by total assets. | | `financial_metrics[].interest_coverage` | EBIT divided by interest expense. | | `financial_metrics[].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. | | `financial_metrics[].payout_ratio` | Declared dividends per common share divided by basic earnings per share. | | `financial_metrics[].revenue_growth` | Revenue growth against the comparable year-earlier period; a non-positive base returns null. | | `financial_metrics[].earnings_growth` | Parent-profit growth against the comparable year-earlier period; a non-positive base returns null. | | `financial_metrics[].operating_income_growth` | Operating-income growth against the comparable year-earlier period; a non-positive base returns null. | | `financial_metrics[].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. | | `financial_metrics[].earnings_per_share_growth` | Basic earnings-per-share growth against the comparable year-earlier period; a non-positive base returns null. | | `financial_metrics[].free_cash_flow_growth` | Free-cash-flow growth against the comparable year-earlier period; a non-positive base returns null. | | `financial_metrics[].book_value_growth` | Parent-equity growth against the comparable year-earlier period; a non-positive base returns null. | | `financial_metrics[].earnings_per_share` | Reported basic earnings per share. | | `financial_metrics[].book_value_per_share` | Closing parent equity divided by closing common shares outstanding. | | `financial_metrics[].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 {#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](https://financialdb.ai/documentation/api/errors-and-limits.md).