Screen Universe by Factor Scores
screen_universeRank companies by cross-sectional factor scores from factor_scores.parquet. Returns the underlying factors (roe, gross_margin, operating_margin, net_profit_margin, revenue_growth_yoy, fcf_to_assets, debt_to_equity, asset_turnover, current_ratio, piotroski_f_score) plus their percentile ranks (1.0 = best in universe, 0.0 = worst). composite_rank (the default sort) is a one-number multi-factor shortcut; sort by a specific *_rank column for a single factor. Two modes: full-universe (omit ticker) or single-entity (ticker set — spot-check ONE company's factor profile). Sector filter is SIC-derived (GICS-aligned, not licensed GICS — see get_pit_universe). Use this instead of get_financial_ratios when you want CROSS-SECTIONAL comparison (rank vs peers); use get_financial_ratios when you want one company's ratios over time. Supports survivorship-free POINT-IN-TIME screening via as_of_date (see the param). Full-universe screens omit rows that don't join to a company (null symbol); pass exclude_outliers=true to also drop shell-company rows with implausible factors. Available on every plan — sample returns the subset covered by the sample bucket.
Input Schema
| Name | Required | Description | Default |
|---|---|---|---|
| limit | No | Number of results to return (1-100). Defaults to 25. | |
| offset | No | Zero-based row offset for paging within the requested `limit` window. At most 250 rows are inlined per call; if the response carries a `truncation` envelope, pass its `next_offset` here. Defaults to 0. | |
| sector | No | Filter to a specific sector (case-insensitive partial match). E.g. 'Technology', 'Healthcare'. | |
| ticker | No | If provided, show only this ticker's factor scores (single-entity mode). Omit to screen the full universe. | |
| sort_by | No | Which factor rank to sort by (see the enum). Defaults to composite_rank. An unrecognized column is rejected with INVALID_ARGUMENT (no silent fallback). | composite_rank |
| as_of_date | No | Point-in-time cutoff (YYYY-MM-DD). When set, the screen is reconstructed as of this date via factor_scores.accepted_at — each entity ranked at its latest-knowable period, zero look-ahead, survivorship-free. Omit for the latest snapshot. | |
| exclude_outliers | No | Optional data-quality guard (default false). When true, additionally drops rows with implausible raw factor values (non-finite, or e.g. asset_turnover > 50x, |FCF/assets| > 10) from shell companies with near-zero denominators. Rows that do not join to a company (null symbol) are ALWAYS omitted in full-universe mode, regardless of this flag. |
Output Schema
| Name | Required | Description | Default |
|---|---|---|---|
| data | Yes | Ranked factor-score rows for the screened universe | |
| note | No | ||
| plan | Yes | Caller's data plan used to scope the screen | |
| _meta | Yes | Provenance envelope — data lineage for every MCP response | |
| ticker | No | Present only when a single-ticker lookup was requested | |
| lineage | No | Provenance for pipeline-derived values (ratio.parquet / factor_scores.parquet): source table + pipeline computed_at, plus a pointer to the tools that return filing-level lineage. NOT point-in-time (recomputed on each pipeline run). | |
| sort_by | Yes | ||
| pit_safe | No | Present (and true) only when as_of_date was supplied — the screen was filtered by factor_scores.accepted_at with zero look-ahead | |
| as_of_date | No | Present only when a point-in-time as_of_date was supplied | |
| truncation | No | Present only when the inline-row cap withheld rows. Page with `next_offset` (keep the same `limit`) or pull the full set via get_compute_ready_stream. | |
| sector_filter | No | Present only when a sector filter was applied | |
| results_returned | Yes |