Screener API

The screener finds every company (or listing) that matches a rule: market cap over $10B, P/E under 20, TTM revenue, GICS sector, a technical signal. It is a latest snapshot, not a history API. It is not Entity Search (Search finds one name; the screener returns a page of names).

Look up metric ids on Screener Metrics if you do not already have them. POST Screener with conditions and fields. Take display_ticker into Entity Reference or a filing tool.

You can search these ids on Coverage — Screener metrics. That table is a snapshot and can be behind the API. For the current list, call Screener Metrics.

CoverageCopy Anchor Link

• When. The current published screener snapshot (the same mart the site screen uses). There is no as-of date and no fiscal-history series here — use Fundamentals for periods.
• Who. Universes: equity (default), etf, fund, person, private_company, or securities (equity + ETF + fund). Default is primary listing only (primary_only=true) and actively trading. Set primary_only=false for every share class and venue line.
• Which metrics. Snapshot columns: profile, price, TTM / latest-quarter / latest-filing fundamentals, ratios, analyst snapshots, technicals. Ids are perioded (ttmRevenue_usd, not revenue). Prefer _usd when comparing across countries. Call Metrics for the list; the “thousands of fields” catalog is not a coverage year.

Screener vs Screener MetricsCopy Anchor Link

Typical flow: Metrics → pick ids → Screener → take display_ticker → Entity Reference or later company-scoped tools.

Screener Metrics without query returns the full catalog. Prefer query=marketCap or query=P/E unless you are building a picker.

What a row isCopy Anchor Link

Default grain is one row per issuer or fund series (primary_only=true): the primary listing we already use on the site.

Set primary_only=false to get every share class and venue line of those issuers (ordinary, ADR, local listing).

Each row’s keys are the metric ids you asked for in fields. There is no fixed column set. display_ticker is the usual handle to pass to Entity Reference as id.

DefaultsCopy Anchor Link

If you omit the scope fields, the screener behaves like the stock screen on the site:

universe=etf / fund / person / private_company switches type. securities is equity + ETF + fund together.

ConditionsCopy Anchor Link

Every filter is:

{ "field": "marketCap_usd", "operator": "over", "values": [10000000000] }

Conditions are AND. Unknown field ids and operators that do not match the metric type are errors — they are not dropped.

values is an array:

Operators by typeCopy Anchor Link

percentile is 0–100 on the current result set (higher is larger). rank is 1 = largest. percent_total is the row’s share of the column total.

Keyword exactly with several values means “any of these” (exchange in US, GY).

Metric idsCopy Anchor Link

Ids are stable strings from Screener Metrics. They are not display labels.

A bare statement name (revenue) is usually not the id. Look up the perioded id (ttmRevenue_usd) on Screener Metrics.

USD vs native currencyCopy Anchor Link

Monetary metrics often exist twice:

• ttmRevenue — as reported in the filer’s currency
• ttmRevenue_usd — converted to USD

marketCap_usd is the USD market-cap column. Prefer _usd when you are comparing names across countries.

CategoriesCopy Anchor Link

Screener Metrics groups ids into:

Entity Attributes, Entity Info, Security Info, Price & Volume, Income Statement, Balance Sheet, Cash Flow Statement, Financial Ratios, Key Metrics, Shares & Float, Dividends & Buybacks, Analyst Estimates, Technical, Other.

query matches id, name, and these labels (query=Key Metrics, query=revenue).

Filter-only metricsCopy Anchor Link

Some ids can appear in conditions but not in fields (filter_only: true). Technical signals and a few virtual filters are in this set. Asking for them in fields is an error.

GICS is a filter on sector (mapped from SIC). You can still return gics_sector as a display column. The label can be empty when we have no mapping.

Identifiers and licensingCopy Anchor Link

You may filter on an ISIN if you already know the field id. We do not return ISINs or CUSIPs. Redistributing those identifiers is not permitted under our licensing.

display_ticker is the screener’s ticker column. It may be a bare symbol (AAPL) or already venue-qualified (TSM US). Pass that string to Entity Reference as id.

How the mart is builtCopy Anchor Link

Rows come from the same screener snapshot the site uses — not a live vendor call.

1. Publish a wide table of entity profile, price, TTM / quarter / filing fundamentals, ratios, analyst snapshots, and technical signal arrays.
2. Primary grain keeps one line per issuer or series. Latest grain keeps every listing.
3. Dedup the latest published_at version of each row at query time.

Screener Metrics reads the field registry for that snapshot (the same fields the site picker uses). It does not scan company rows.

Request shapeCopy Anchor Link

Screener is POST /v2/screener because conditions and fields are JSON arrays. MCP tools/call is JSON arguments either way. Screener Metrics is GET /v2/screener/metrics.

Response shapeCopy Anchor Link

Screener returns { universe, primary_only, actively_trading, page, size, total, total_pages, has_next, has_prev, sort_by, sort_order, fields, conditions, results }. conditions echoes the filters you sent plus the actively-trading default when it was applied. Universe and primary-only are top-level fields, not repeated in conditions. An empty results array is a valid miss, not an error.

Screener Metrics returns { query, count, categories, metrics }. query is null when you asked for the full catalog.

RelatedCopy Anchor Link