/api/v1/financials/ratiosGet derived financial ratios (margins, returns, growth, leverage) over time.
Get derived financial ratios (margins, returns, growth, leverage) over time.
5 tokensSince v3.4.0
Why use this
Retrieve calculated financial ratios separated from raw metrics.
Common use case
Trend analysis of profitability, leverage, liquidity, and growth metrics. Filter by ratio category.
29 derived financial ratios computed from the standardized XBRL primitives surfaced by GET /api/v1/financials/metrics. Categories: profitability (gross/operating/net margins + ROE/ROA/ROIC), leverage (debt-to-equity, debt-to-assets, interest coverage), liquidity (current + quick ratios), efficiency (asset/inventory/receivables turnover), per_share (TTM EPS, BVPS, FCFPS), runway (cash_runway_status tier), growth (YoY + QoQ revenue + EPS). All ratios are unit-aware: ratios are decimals (0.15 = 15%), runway is a string tier label, per-share metrics are USD per share. ROE/ROA/ROIC use AVERAGED balance-sheet denominators per the v3.7.2 DO-parity fix. Use GET /api/v1/financials/snapshot for a single-call TTM summary or GET /api/v1/financials/screen to run multi-ratio AND-style screens across the ~7,000-ticker universe.
Parameters
| Name | In | Required | Default | Allowed | Description | Example |
|---|---|---|---|---|---|---|
| ticker | query | required | — | — | Stock ticker symbol (canonical hyphen form). Returns 404 on tickers without XBRL coverage; gate via `/api/v1/financials/tickers`. | AAPL |
| period | query | optional | Q | — | Period type: `Q` (quarterly point-in-time ratios), `Y` (annual), or `TTM` (trailing-twelve-month rolling — most useful for cross-issuer comparison since it smooths quarterly seasonality). For most fundamental-screener UIs, default to `TTM`. | TTM |
| years | query | optional | 5 | — | Years of history (1-20). With `period=Q` returns up to `years × 4` rows; with `period=Y` or `period=TTM` returns up to `years` rows. TTM rolls the 4-quarter window forward by one quarter per row. | 5 |
| category | query | optional | all | — | Filter to one ratio category: `profitability` (margins + ROE/ROA/ROIC), `leverage` (debt-to-equity, interest coverage), `liquidity` (current/quick ratios), `efficiency` (asset/inventory turnover), `per_share` (EPS, BVPS, FCFPS), `runway` (cash-runway-status tier), `growth` (YoY/QoQ revenue + EPS), or `all` (everything). Use `category=profitability` for margin-trend charts; `category=leverage` for credit-risk dashboards. | profitability |
Response schema
| Field | Type | Nullable | Description |
|---|---|---|---|
| data.company | string | no | Company name (Title Case from EDGAR's company-tickers.json). |
| data.ticker | string | no | Issuer ticker echoed back (canonical hyphen form). |
| data.period_type | string | no | Echoed back: `Q`, `Y`, or `TTM`. TTM rows are computed by summing the most-recent 4 quarterly DURATION facts (revenue, net_income, OCF, capex) and using the latest INSTANT fact for balance-sheet denominators. |
| data.category | string | no | Echoed-back filter: `profitability` / `leverage` / `liquidity` / `efficiency` / `per_share` / `runway` / `growth` / `all`. When `all` is selected, every ratio in the response carries the same shape regardless of category. |
| data.data[] | array | no | Array of period rows, sorted by `period_end DESC` (most recent first). Empty array on tickers without parsed XBRL data. |
| data.data[].period_end | string | no | ISO `YYYY-MM-DD` fiscal-period-end date. NOT calendar-aligned for non-calendar fiscal years. |
| data.data[].gross_margin | number | yes | Gross margin (UNIT: ratio, decimal — `0.473` = 47.3%). Computed as `gross_profit / revenue`. Null when either input is null. Profitability category. |
| data.data[].operating_margin | number | yes | Operating margin (decimal). `operating_income / revenue`. Negative for operating-loss companies. Profitability category. |
| data.data[].net_margin | number | yes | Net margin (decimal). `net_income / revenue`. Negative for loss-makers. Profitability category. |
| data.data[].roe | number | yes | Return on Equity (decimal). For TTM uses AVERAGED denominator: `ttm_net_income / avg_book_equity` (per the v3.7.2 DO-parity fix — non-averaged denominators inflate ROE on rapidly-changing equity). Null when book equity is negative or one of the inputs is missing. Profitability category. |
| data.data[].roa | number | yes | Return on Assets (decimal). `ttm_net_income / avg_total_assets` (averaged denominator for TTM). Profitability category. |
| data.data[].roic | number | yes | Return on Invested Capital (decimal). v3.5.0 DO-parity formula: `ttm_nopat / (avg_equity + avg_total_debt - avg_cash)` where `nopat = ebit × (1 - 0.25 fixed tax)`. The classic compounder-quality metric — Buffett-style screens use ROIC > 0.15. Profitability category. |
| data.data[].debt_to_equity | number | yes | Total debt / book equity (ratio). INSTANT-on-INSTANT (point-in-time at period_end). Null when equity is zero or negative. Below 0.5 = conservative; above 2.0 = leveraged. Leverage category. |
| data.data[].current_ratio | number | yes | Current assets / current liabilities (ratio). Liquidity category. Below 1.0 indicates short-term-funding gap (note: AAPL routinely runs <1.0 with no liquidity issue — interpret in context). Liquidity category. |
| data.data[].quick_ratio | number | yes | (Current assets - inventory) / current liabilities (ratio). Strict-liquidity test excluding inventory. Liquidity category. |
| data.data[].eps_diluted_ttm | number | yes | Trailing-twelve-month diluted EPS (USD per share). Sum of last 4 quarterly `eps_diluted` values. NOT split-adjusted server-side — for split-adjusted EPS history use `/api/v1/tickers/{ticker}/overview`. Per-share category. |
| data.data[].book_value_per_share | number | yes | Book value per share (USD). `total_equity / shares_outstanding`. Negative for issuers with negative book equity. Per-share category. |
| data.data[].free_cash_flow_per_share | number | yes | TTM Free Cash Flow per share (USD). `ttm_free_cash_flow / shares_outstanding`. Negative for FCF-burning companies. Per-share category. |
| data.data[].revenue_growth_yoy | number | yes | Year-over-year revenue growth (decimal — `0.061` = 6.1% growth). Computed as `(period_revenue / prior_year_same_period_revenue) - 1`. Null on the first year of coverage (no prior baseline). Growth category. |
| data.data[].eps_growth_yoy | number | yes | Year-over-year diluted EPS growth (decimal). Same formula shape as revenue_growth_yoy. Negative when EPS shrank YoY. Null when prior-year EPS is zero/negative (division undefined). Growth category. |
| data.data[].cash_runway_status | string | yes | Tiered cash-runway label (added v3.6.0). Values: `cash_generating` (FCF-positive, no runway concept), `healthy` (>24 months runway at current burn), `moderate` (12-24 months), `caution` (6-12 months), `critical` (<6 months). Useful for filtering distressed-equity candidates and biotech/clinical-stage screens. Runway category. |
Sample response
·
- "status": "success"
- "data":
- "company": "Apple Inc."
- "ticker": "AAPL"
- "period_type": "TTM"
- "category": "all"
- "data":
Errors
| Status | Label | Description |
|---|---|---|
| 200 | OK | Request succeeded. |
| 400 | Bad Request | Invalid query, body, or path parameter. |
| 401 | Unauthorized | Missing or invalid Authorization header / api_Token. |
| 402 | Payment Required | Insufficient token balance for this call. Top up |
| 429 | Too Many Requests | Rate limit exceeded for your tier (see /pricing for tier limits). Tier limits |
| 500 | Server Error | Unexpected server-side failure. Retry with backoff; report if persistent. |
Code samples
curl "https://api.finradar.ai/api/v1/financials/ratios?api_Token=YOUR_API_KEY" \
-H "Authorization: Bearer YOUR_JWT_TOKEN"Generate an API key in /account/credentials to run live queries (literal YOUR_API_KEY placeholder shown until then).