API ReferenceFundamentals
Stock screener
/api/v3/fundamentals/screener- Plan
- Free and up
- Price
- 1 credit per call
- MCP tool
fundamentals_screener
Multi-filter stock screener combining profitability (ROE, ROA, net margin), growth (revenue, EPS), financial-health (debt/equity, current ratio) and dividend filters, with sector/industry scoping. Results are sized, floored and sorted on our own data: market_cap_usd and adv_21d_usd from exchange prices and shares outstanding, common equity only unless security_class asks for more, and revenue_usd / net_income_usd only where the reporting currency is established (raw revenue stays in the issuer's own currency and is not comparable across rows). Default floors: $300M market cap and $1M/day dollar volume. The response carries field_sources and as_of; liquid listings the market-cap floor dropped for lack of a verifiable size are named in universe.liquid_without_market_cap, and a row still filed under a symbol its issuer retired in the last 18 months is sized on the current listing (listing_ticker). market_cap_usd is null when the close moved more than 3x (either way) from the split-adjusted close on the share count's own date, genuine moves included: the count is not trusted; such rows leave floored screens and, when they trade at least $1M a day, are named with the reason. While its size data warms on a fresh server it returns 503 build_timeout with Retry-After; when that data or the fundamentals source cannot be read it returns 503 upstream_unavailable (error_code screener_size_data_unavailable or screener_vendor_unavailable; refunded), never an empty list. PRIMARY tool for 'find me stocks that…' asks; ready-made strategies live in /fundamentals/screener/presets. UNITS: filters ending in _pct are PERCENT numbers (roe_min_pct=20 means ROE >= 20%, and 0.5 means 0.5%); the older names (roe_min, revenue_growth_min, ...) are the same percent unit and refuse a value between -1 and 1 as ambiguous (422 ambiguous_percent_threshold, refunded). debt_to_equity_max and current_ratio_min are MULTIPLES (0.5 = 0.5x). Row ratios, margins, growth and payout are percent numbers and debt_to_equity / current_ratio / quick_ratio multiples, for each row's latest fiscal year (fiscal_year), not TTM; the response states every filter it applied with its unit (filters_applied) and every field's unit (units). Rows with negative equity carry equity_negative and never pass a D/E ceiling. Revenue growth beyond +-100% is checked against the issuer's SEC annual report (growth_status, revenue_growth_basis; the vendor's figure stays in vendor_revenue_growth_yoy) and the growth filter is applied again to the checked figure; a company the source excluded on a wrong figure cannot be recovered. Over MCP an argument this tool does not declare is refused with the accepted list, never ignored. gross_margin_min_pct, operating_margin_min_pct (percent) and revenue_min_usd / revenue_max_usd (USD, on revenue_usd) are applied by this screener to the served rows, after the source's filters; a row without the figure does not pass, and local_filters echoes them.
Parameters
Query
sectorstringOptionalThe source's sector name, e.g. Technology, Healthcare, Financial Services.
industrystringOptionalThe source's industry name, e.g. Semiconductors, Insurance - Property & Casualty.
roe_min_pctnumberOptionalMinimum return on equity in PERCENT: 20 keeps ROE >= 20%; 0.5 keeps ROE >= 0.5%. Each row's latest fiscal year (not TTM): net income / average shareholders' equity.
roe_max_pctnumberOptionalMaximum return on equity in PERCENT: 50 keeps ROE <= 50%. Latest fiscal year, net income / average shareholders' equity.
roa_min_pctnumberOptionalMinimum return on assets in PERCENT: 10 keeps ROA >= 10%. Latest fiscal year, net income / total assets at year end.
net_margin_min_pctnumberOptionalMinimum net margin in PERCENT: 15 keeps net income / revenue >= 15%. Latest fiscal year.
revenue_growth_min_pctnumberOptionalMinimum revenue growth vs the prior fiscal year in PERCENT: 20 keeps growth >= 20%; -10 admits declines of up to 10%. Latest fiscal year. Growth beyond +-100% is checked against the SEC annual report and this floor is applied again to the checked figure.
eps_growth_min_pctnumberOptionalMinimum diluted-EPS growth vs the prior fiscal year in PERCENT: 25 keeps EPS growth >= 25%. Latest fiscal year.
payout_ratio_max_pctnumberOptionalMaximum payout ratio in PERCENT: 60 keeps dividends paid / net income <= 60%. Latest fiscal year.
gross_margin_min_pctnumberOptionalMinimum gross margin in PERCENT (40 = 40%), latest fiscal year. Applied by this screener to the served rows; a row without it does not pass.
operating_margin_min_pctnumberOptionalMinimum operating margin in PERCENT, latest fiscal year. Applied by this screener to the served rows.
revenue_min_usdnumberOptionalMinimum revenue in USD (revenue_usd, latest fiscal year). A row whose USD revenue is not established does not pass.
revenue_max_usdnumberOptionalMaximum revenue in USD (revenue_usd, latest fiscal year). A row whose USD revenue is not established does not pass.
gross_margin_minnumberOptionalAlias of gross_margin_min_pct (PERCENT); a value between -1 and 1 is refused as ambiguous (422).
operating_margin_minnumberOptionalAlias of operating_margin_min_pct (PERCENT); a value between -1 and 1 is refused as ambiguous (422).
revenue_minnumberOptionalAlias of revenue_min_usd (USD).
revenue_maxnumberOptionalAlias of revenue_max_usd (USD).
roe_minnumberOptionalDeprecated: same as roe_min_pct, in PERCENT (20 = 20%). A value strictly between -1 and 1 other than 0 is refused as ambiguous (422 ambiguous_percent_threshold); roe_min_pct is never refused for size.
roe_maxnumberOptionalDeprecated: same as roe_max_pct, in PERCENT (50 = 50%). Values strictly between -1 and 1 other than 0 are refused as ambiguous (422).
roa_minnumberOptionalDeprecated: same as roa_min_pct, in PERCENT (10 = 10%). Values strictly between -1 and 1 other than 0 are refused as ambiguous (422).
net_margin_minnumberOptionalDeprecated: same as net_margin_min_pct, in PERCENT (15 = 15%). Values strictly between -1 and 1 other than 0 are refused as ambiguous (422).
revenue_growth_minnumberOptionalDeprecated: same as revenue_growth_min_pct, in PERCENT (20 = 20%). Values strictly between -1 and 1 other than 0 are refused as ambiguous (422).
eps_growth_minnumberOptionalDeprecated: same as eps_growth_min_pct, in PERCENT (25 = 25%). Values strictly between -1 and 1 other than 0 are refused as ambiguous (422).
debt_to_equity_maxnumberOptionalMaximum total debt / shareholders' equity as a MULTIPLE, not a percent: 0.5 keeps debt <= half of equity, 1 keeps debt <= equity. 0 to 20, else 422 debt_to_equity_max_out_of_range. Latest fiscal year end. Companies with negative equity (negative D/E, equity_negative) never pass.
current_ratio_minnumberOptionalMinimum current assets / current liabilities as a MULTIPLE: 1.5 keeps a current ratio >= 1.5x. Latest fiscal year end.
years_dividend_growth_minintegerOptionalMinimum consecutive years of dividend-per-share growth, in YEARS: 10 keeps streaks of 10 or more.
payout_ratio_maxnumberOptionalDeprecated: same as payout_ratio_max_pct, in PERCENT (60 = 60%). Values strictly between -1 and 1 other than 0 are refused as ambiguous (422).
sort_bystringOptionalSorted over the whole matched set, nulls last. The short spellings are aliases: market_cap/marketcap -> market_cap_usd, revenue -> revenue_usd, net_income -> net_income_usd, adv/adv_21d/adv_usd/dollar_volume -> adv_21d_usd, price -> price_usd, and *_growth -> *_growth_yoy. revenue and net_income sort in USD, never on the issuer's own currency. Any other key is a 400 listing the allowed ones.
market_cap_usdadv_21d_usdprice_usdrevenue_usdnet_income_usdrevenue_growth_yoynet_income_growth_yoyeps_growth_yoyroeroagross_marginoperating_marginnet_margindebt_to_equitycurrent_ratioquick_ratiopayout_ratiodividend_growth_yoyyears_dividend_growthmarket_capmarketcaprevenuenet_incomeadvadv_21dadv_usddollar_volumepricerevenue_growtheps_growthnet_income_growthdividend_growthmarket_cap_usdsort_orderstringOptionalDesc (default) or asc; rows without a value sort last either way.
ascdescdesclimitintegerOptionalRows per page, 1 to 100.
501 to 100pageintegerOptionalPage of the whole matched and sorted set, from 1.
11 to 100min_market_cap_usdnumberOptionalIssuer market-cap floor, USD. 0 disables it and also admits rows whose market cap is unknown (ADRs, funds).
3000000000 to 1000000000000min_adv_usdnumberOptionalFloor on 21-session average daily dollar volume, USD. 0 disables it.
10000000 to 10000000000security_classstringOptionalComma list of classes to include: common, adr, preferred, fund, unit, warrant, other. Unknown classes are a 400.
commonResponse
A 200 is a JSON envelope: ok: true and this endpoint's own fields (see Fundamentals). It carries X-Request-ID, the credit headers (X-Credits-Cost, X-Credits-Remaining, X-Credits-Receipt, X-Credits-Settlement) and the rate-limit headers.
A 200 is billed even when it holds no data (an empty list, null, found: false), so check those fields. Pricing & credits explains the credit headers.
Errors
No error is billed. The body is { "ok": false, "error", "detail", "request_; read the code from error.
| Error | Meaning |
|---|---|
400 invalid_ticker | The request is malformed, for example a ticker that is not a symbol: invalid_ticker, refused before any credit is reserved, with param naming the parameter. Not billed. |
401 unauthorized | Missing or invalid API key. |
402 plan_required | Your plan does not include this tool, you are out of credits, or your workspace's spend cap paused its keys. plan_required names the plan that unlocks the tool; usage_exceeded means the credit balance is spent; spend_cap_reached means the key is paused until the cap resets or is raised: detail names the cap and the reset, cap_usd and resets_at (ISO 8601) carry them, and doc_url links pricing and credits. Not billed. |
403 scope_denied | This API key is limited to some products and this tool is not one of them. product names the tool's product and scopes the key's products. An upgrade does not change it: use a key whose scopes include the product, or change this key's scopes. Not billed. |
404 not_found | No such resource. Not billed. |
422 validation | A parameter is missing, out of range or the wrong type; param names it. Not billed. |
429 rate_limited | Your plan's rate limit is spent for this window. Retry after Retry-After seconds. Not billed. |
503 paid_ | The data could not be served completely right now; retry later. Not billed. |
504 request_timeout | The request ran past the server's time budget; retry. Not billed. |
This table lists what the spec declares for this route. Error responses lists every code FIRM sends, with when to retry.
Guides
Read the Fundamentals guide for this endpoint's fields and examples.