stocks_screen

Cross-sectional company screener over the latest metrics snapshot.

Use this to find and rank companies meeting numeric or classifier criteria; use stocks_get_financial_metrics when you already know one ticker and need its multi-period definitions and formula inputs. The shared envelope echoes data.filters and the effective data.sort; data.companies contains identity (ticker, cik, company_name, exchange, sector, sic_code) and the filtered/sorted metric values. Each value is an exact decimal string with unit, currency, fiscal frame, as_of, and source. meta.as_of is when the current snapshot rebuild completed.

Monetary line items filter and rank in each company's reporting currency (each value carries currency); ratio and growth metrics are the cross-currency-comparable choice.

Clean public metrics are: gross_margin, operating_margin, net_margin, fcf_margin, revenue_growth_yoy, revenue_cagr_3y, net_income_growth_yoy, net_income_cagr_3y, fcf_growth_yoy, fcf_cagr_3y, roe, roa, roic, debt_to_equity, net_debt_to_ebitda, current_ratio; flow lines revenue, cost_of_revenue, gross_profit, operating_income, pretax_income, income_tax_expense, net_income, net_cash_operating, capex, depreciation_amortization; instant lines total_assets, total_equity, cash_and_equivalents, debt_current, debt_noncurrent, current_assets, current_liabilities, shares_outstanding; and derived free_cash_flow, total_debt. Internal-only price-derived metrics are: market_cap, pe_ttm, ps_ttm, pb, ev_ebitda, fcf_yield. Ratio values are fractions, so 0.2 means 20%.

Classifiers are nominal company attributes: exchange (as SEC reports it, e.g. Nasdaq, NYSE), sic_code (the filer's 4-digit SEC SIC as a zero-padded string, e.g. 7372 for prepackaged software), and sector — a coarse bucket we derive from SIC, one of: Communication Services, Consumer Discretionary, Consumer Staples, Energy, Financials, Health Care, Industrials, Materials, Real Estate, Technology, Utilities. Use sector for a broad cut and sic_code to pin an exact industry. An unrecognized sector value is bad_parameter, not an empty result. Companies we have not yet classified carry a null sector and are excluded by any sector filter.

Filters are ANDed. A company missing any filtered metric is excluded, and a company missing the sort metric is also excluded because ranked ordering requires a value. Classifiers support eq and in but cannot be sorted. A classifier-only screen must supply an explicit numeric sort. Results are bounded: default 20, maximum 100. Pass pagination.next_cursor back as cursor while has_more is true.

Errors use bad_parameter for unknown metrics, incompatible operations or values, an undefined ranking, bad bounds, or a malformed cursor. A public request involving any internal-only metric returns out_of_license and names it; use an internal credential for price-derived screening.

Example: stocks_screen(filters=[{"metric":"sector","op":"eq", "value":"Technology"},{"metric":"revenue_growth_yoy","op":"gt", "value":"0.25"}], sort={"metric":"revenue","direction":"desc"}, limit=20).