/api/v1/financials/screenScreen stocks by financial ratio criteria.
Screen stocks by financial ratio criteria. Supports greater-than and less-than filters on 20+ financial metrics.
10 tokensSince v3.5.0
Why use this
The XBRL-driven stock screener — filter the ~7,000-company financials universe by 20+ derived ratio criteria (profitability, leverage, liquidity, efficiency, growth) using composable greater-than / less-than filters. Built on the same standardized XBRL ratio engine as `/financials/ratios` so the math is consistent across endpoints. Each result row carries the full ratio block (P/E, P/B, ROE, ROIC, EBITDA margin, debt-to-equity, cash-runway-status, sector/industry) so dashboards can render results without follow-up per-ticker calls. The right entry point for fundamental-screener UIs and quant pre-screens (e.g. 'find all companies with ROE > 15%, debt-to-equity < 1, and positive FCF margin'). For per-ticker drill-downs use `/financials/metrics` (line items) or `/financials/snapshot` (TTM summary).
Common use case
Stock screener: find all companies with ROE > 15%, debt-to-equity < 1, and positive FCF margin. Chain with /snapshot for details.
Stock screener built on top of XBRL-derived ratios — 20+ filters (P/E, P/B, ROE, ROIC, EBITDA-margin, debt-to-equity, current ratio, cash-runway-status, etc.). Each row carries the full ratio block so customers do not need a follow-up call to render results. Pair with GET /api/v1/financials/metrics to drill into one ticker's standardized financial line items.
Parameters
| Name | In | Required | Default | Allowed | Description | Example |
|---|---|---|---|---|---|---|
| gross_margin_gt | query | optional | — | — | Keep only companies whose gross margin is greater than this value (decimal, e.g. 0.15 = 15%). | 0.35 |
| gross_margin_lt | query | optional | — | — | Keep only companies whose gross margin is less than this value (decimal, e.g. 0.15 = 15%). | 0.35 |
| operating_margin_gt | query | optional | — | — | Keep only companies whose operating margin is greater than this value (decimal, e.g. 0.15 = 15%). | 0.15 |
| operating_margin_lt | query | optional | — | — | Keep only companies whose operating margin is less than this value (decimal, e.g. 0.15 = 15%). | 0.15 |
| net_margin_gt | query | optional | — | — | Keep only companies whose net margin is greater than this value (decimal, e.g. 0.15 = 15%). | 0.10 |
| net_margin_lt | query | optional | — | — | Keep only companies whose net margin is less than this value (decimal, e.g. 0.15 = 15%). | 0.10 |
| fcf_margin_gt | query | optional | — | — | Keep only companies whose free-cash-flow margin is greater than this value (decimal, e.g. 0.15 = 15%). | 0.10 |
| fcf_margin_lt | query | optional | — | — | Keep only companies whose free-cash-flow margin is less than this value (decimal, e.g. 0.15 = 15%). | 0.10 |
| roe_gt | query | optional | — | — | Keep only companies whose ROE is greater than this value (decimal, e.g. 0.15 = 15%). | 0.15 |
| roe_lt | query | optional | — | — | Keep only companies whose ROE is less than this value (decimal, e.g. 0.15 = 15%). | 0.15 |
| roa_gt | query | optional | — | — | Keep only companies whose ROA is greater than this value (decimal, e.g. 0.15 = 15%). | 0.08 |
| roa_lt | query | optional | — | — | Keep only companies whose ROA is less than this value (decimal, e.g. 0.15 = 15%). | 0.08 |
| roic_gt | query | optional | — | — | Keep only companies whose ROIC is greater than this value (decimal, e.g. 0.15 = 15%). | 0.12 |
| roic_lt | query | optional | — | — | Keep only companies whose ROIC is less than this value (decimal, e.g. 0.15 = 15%). | 0.12 |
| debt_to_equity_gt | query | optional | — | — | Keep only companies whose debt-to-equity ratio is greater than this value (ratio). | 1.0 |
| debt_to_equity_lt | query | optional | — | — | Keep only companies whose debt-to-equity ratio is less than this value (ratio). | 1.0 |
| debt_to_assets_gt | query | optional | — | — | Keep only companies whose debt-to-assets ratio is greater than this value (ratio). | 0.5 |
| debt_to_assets_lt | query | optional | — | — | Keep only companies whose debt-to-assets ratio is less than this value (ratio). | 0.5 |
| current_ratio_gt | query | optional | — | — | Keep only companies whose current ratio is greater than this value (ratio). | 1.5 |
| current_ratio_lt | query | optional | — | — | Keep only companies whose current ratio is less than this value (ratio). | 1.5 |
| quick_ratio_gt | query | optional | — | — | Keep only companies whose quick ratio is greater than this value (ratio). | 1.0 |
| quick_ratio_lt | query | optional | — | — | Keep only companies whose quick ratio is less than this value (ratio). | 1.0 |
| asset_turnover_gt | query | optional | — | — | Keep only companies whose asset turnover is greater than this value (ratio). | 1.0 |
| asset_turnover_lt | query | optional | — | — | Keep only companies whose asset turnover is less than this value (ratio). | 1.0 |
| interest_coverage_gt | query | optional | — | — | Keep only companies whose interest coverage is greater than this value (ratio). | 5.0 |
| interest_coverage_lt | query | optional | — | — | Keep only companies whose interest coverage is less than this value (ratio). | 5.0 |
| inventory_turnover_gt | query | optional | — | — | Keep only companies whose inventory turnover is greater than this value (ratio). | 5.0 |
| inventory_turnover_lt | query | optional | — | — | Keep only companies whose inventory turnover is less than this value (ratio). | 5.0 |
| receivables_turnover_gt | query | optional | — | — | Keep only companies whose receivables turnover is greater than this value (ratio). | 8.0 |
| receivables_turnover_lt | query | optional | — | — | Keep only companies whose receivables turnover is less than this value (ratio). | 8.0 |
| revenue_growth_yoy_gt | query | optional | — | — | Keep only companies whose YoY revenue growth is greater than this value (decimal, e.g. 0.15 = 15%). | 0.20 |
| revenue_growth_yoy_lt | query | optional | — | — | Keep only companies whose YoY revenue growth is less than this value (decimal, e.g. 0.15 = 15%). | 0.20 |
| eps_growth_yoy_gt | query | optional | — | — | Keep only companies whose YoY EPS growth is greater than this value (decimal, e.g. 0.15 = 15%). | 0.15 |
| eps_growth_yoy_lt | query | optional | — | — | Keep only companies whose YoY EPS growth is less than this value (decimal, e.g. 0.15 = 15%). | 0.15 |
| revenue_growth_qoq_gt | query | optional | — | — | Keep only companies whose QoQ revenue growth is greater than this value (decimal, e.g. 0.15 = 15%). | 0.05 |
| revenue_growth_qoq_lt | query | optional | — | — | Keep only companies whose QoQ revenue growth is less than this value (decimal, e.g. 0.15 = 15%). | 0.05 |
| eps_growth_qoq_gt | query | optional | — | — | Keep only companies whose QoQ EPS growth is greater than this value (decimal, e.g. 0.15 = 15%). | 0.05 |
| eps_growth_qoq_lt | query | optional | — | — | Keep only companies whose QoQ EPS growth is less than this value (decimal, e.g. 0.15 = 15%). | 0.05 |
Response schema
| Field | Type | Nullable | Description |
|---|---|---|---|
| rows | array | no | Array of screen-result rows — each ticker that satisfies ALL filters (AND-combined). Sorted by ticker alphabetically by default; pass `sort_by` parameter to sort by ratio (e.g. `sort_by=roe&sort_order=desc` for ROE-ranked output). Empty array on overly-narrow filter combinations. |
| rows[].ticker | string | no | Issuer ticker (canonical hyphen form). Pass to `/financials/snapshot` or `/financials/metrics` for per-ticker drill-downs. |
| rows[].company_name | string | no | Company name from EDGAR's company-tickers.json (typically Title Case). Use for human-readable labels in screener UIs. |
| rows[].pe_ratio | number | yes | TTM (trailing 12 months) Price / Earnings ratio. Computed as `current_price / ttm_eps_diluted`. Null when EPS is negative (earnings-loss companies) — interpret null as 'P/E undefined for loss-makers'. Use `pe_lt=20` to filter to value names; combine with `pe_gt=0` to exclude loss-makers. |
| rows[].pb_ratio | number | yes | TTM Price / Book ratio. Computed as `current_price / book_value_per_share`. Null when book value is negative (rare; some heavily-distressed companies). `pb_lt=1` is the classic deep-value Graham filter; `pb_gt=10` typical for high-quality compounders. |
| rows[].roe | number | yes | TTM Return on Equity, computed using AVERAGED denominator (`ttm_net_income / avg_book_equity`) per the v3.7.2 DO-parity fix. Decimal value (`0.15` = 15%). Null when book equity is negative or when one of the inputs is missing. ROE > 0.20 indicates high-quality compounder territory. |
| rows[].roic | number | yes | TTM Return on Invested Capital using the v3.5.0 DO-formula (`ttm_nopat / (avg_equity + avg_total_debt - avg_cash)`, with NOPAT = EBIT × (1 - 0.25 fixed tax)). Decimal value. The classic compounder-quality metric — Buffett-style screens use ROIC > 0.15. |
| rows[].ebitda_margin | number | yes | TTM EBITDA / TTM Revenue. Decimal value (`0.30` = 30% margin). Null when revenue is zero or near-zero (rare). Useful for capital-intensity / scale-quality screens — software companies typically 25-40%; commodity producers 10-20%. |
| rows[].debt_to_equity | number | yes | Total debt (short + long) / book equity, point-in-time at the latest fiscal-period end. Null when book equity is negative or zero. Below 0.5 indicates conservative balance sheet; above 2.0 indicates leveraged. Banks and insurers are excluded from typical screens (their structural leverage skews comparison). |
| rows[].cash_runway_status | string | yes | Tiered cash-runway label (added v3.6.0): `healthy` (>24 months runway at current burn), `moderate` (12-24 months), `caution` (6-12 months), `critical` (<6 months). Null for profitable companies (no runway concept). Useful for filtering distressed-equity candidates and biotech/clinical-stage screens. |
| rows[].sector | string | yes | Sharadar sector classification. Null when ticker is unmapped in Sharadar. Pre-filter screens with `sector` parameter to avoid sector-bias in cross-industry-incomparable ratios (e.g. ROE comparisons across Banks vs Tech). |
| rows[].industry | string | yes | Sharadar industry classification (more specific than `sector`). Em-dash characters preserved verbatim from Sharadar. |
| meta | object | no | Result metadata: `{ total: integer, applied_filters: array<string>, ... }`. `applied_filters` echoes the parsed `_gt`/`_lt` filters as human-readable strings (e.g. `["roe > 0.15", "debt_to_equity < 1.0"]`) — useful for dashboards rendering 'currently filtered by:' breadcrumbs. |
Sample response
·
- "status": "success"
- "data":
- "filters":
- "count": 847
- "results":
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/screen?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).