List screener filters

Operation id: list_screen_filters — REST POST /api/v1/research/list_screen_filters, MCP tool list_screen_filters.

When should you use List screener filters?

• The user wants filters for an idea — cheap stocks, momentum, dividends — or asks what the screener can filter on.
• Before building a screener, to find the ids of the filters to use.

Use another operation when:

• You already know the filter and need its inputs, relations and allowed values — use describe_screen_filter instead.
• You have chosen the filters and want the screener built — use create_screener instead.

What parameters does List screener filters take?

• query (optional; string; 1–80 characters) — Words to look for, ignoring case, in each filter's name and description.
• concept (optional; string; one of value, momentum, quality, dividends, volatility, size, liquidity, solvency, risk_reward) — An investing concept, mapped to catalogue subcategories: value (valuation ratios), momentum, quality (profitability and operating margin), dividends, volatility, size (company profile), liquidity, solvency and risk_reward.
• level (optional; string; one of asset, sector, market) — asset for filters on the instrument itself, sector for its sector's aggregate, market for the whole market's.
• category (optional; string; one of fundamental, technical, market_and_sector) — fundamental, technical or market_and_sector.
• assetType (optional; string; one of stocks, etps, crypto) — Only filters that apply to this asset type: stocks, etps or crypto.
• limit (optional; integer; from 1 to 200; default 25; unit: a count) — How many filters to return in this page.
• offset (optional; integer; at least 0; default 0; unit: a count) — How many matching filters to skip, to read the next page.

What does List screener filters return?

The result object holds the fields below. Every result also carries a text summary, the assumed values and the dataVersion, as the reference describes.

• filters (list) — The matching filters, in catalogue order.
• filters[].id (string) — The filter's stable public id — pass it to describe_screen_filter and to screener rows.
• filters[].name (string; at least 1 characters) — The filter's name as the screener shows it.
• filters[].level (string; one of asset, sector, market) — asset, sector or market.
• filters[].category (string; one of fundamental, technical, market_and_sector) — fundamental, technical or market_and_sector.
• filters[].subcategory (string; at least 1 characters) — The catalogue's subcategory, such as Valuation Ratios.
• filters[].description (string; at least 1 characters) — The catalogue's description of what the filter measures.
• filters[].appliesTo (list) — The asset types the filter applies to.
• filters[].inputs (list) — The inputs the filter takes, by input id — how many months or reports ago its value is read, or the window it is measured over.
• filters[].relations (list) — The kinds of comparison the filter supports: compare_to_value, between, highest_lowest, compare_to_aggregate, compare_to_own_past, special.
• filters[].defaultRelation (string; one of greater_than, less_than, greater_or_equal, less_or_equal, between, highest, lowest, equal, price_above, price_below, crossing_above_within_days, crossing_below_within_days, strongly_overvalued, overvalued, in_range, undervalued, strongly_undervalued, fast_bull_crossover_within_days, fast_bear_crossover_within_days, slow_bull_crossover_within_days, slow_bear_crossover_within_days, fast_over_slow_bull_crossover_within_days, fast_over_slow_bear_crossover_within_days) — The relation the screener proposes first for this filter.
• total (integer; at least 0; unit: a count) — How many filters matched in all.
• offset (integer; at least 0; unit: a count) — How many matching filters were skipped.
• limit (integer; at least 1; unit: a count) — The most filters this page could hold.

What does a call to List screener filters look like?

The first two value filters

Asked as: What filters can I use to find cheap stocks?

# Caller on the free plan
POST /api/v1/research/list_screen_filters
Authorization: Bearer <API key or access token>
Content-Type: application/json

{
  "concept": "value",
  "limit": 2
}

The result:

{
  "filters": [
    {
      "id": "p_e_positive",
      "name": "P/E (Positive)",
      "level": "asset",
      "category": "fundamental",
      "subcategory": "Valuation Ratios",
      "description": "The Price to Earnings ratio indicates the dollar amount an investor can expect to invest in a company in order to receive $1 of that company’s earnings. Low P/E indicate that the current stock price is low relative to earnings. Negative P/E values are discarded to avoid problems when screening for low P/E values.",
      "appliesTo": [
        "stocks"
      ],
      "inputs": [
        "months_ago"
      ],
      "relations": [
        "compare_to_value",
        "between",
        "highest_lowest",
        "compare_to_aggregate"
      ],
      "defaultRelation": "less_than"
    },
    {
      "id": "p_e",
      "name": "P/E",
      "level": "asset",
      "category": "fundamental",
      "subcategory": "Valuation Ratios",
      "description": "The Price to Earnings ratio indicates the dollar amount an investor can expect to invest in a company in order to receive $1 of that company’s earnings.",
      "appliesTo": [
        "stocks"
      ],
      "inputs": [
        "months_ago"
      ],
      "relations": [
        "compare_to_value",
        "between",
        "highest_lowest",
        "compare_to_aggregate",
        "compare_to_own_past"
      ],
      "defaultRelation": "between"
    }
  ],
  "total": 9,
  "offset": 0,
  "limit": 2
}

The summary it returns:

9 filters match the concept value; showing the first 2: P/E (Positive) and P/E.

The values it assumed, because the request left them out:

• /offset = 0 — no offset was given, so the list starts at the first match

What goes wrong most often with List screener filters?

• The rows of a screener apply in order, so a highest or lowest N row ranks only what the rows before it kept.
• A filter that applies only to stocks — most fundamental filters do — selects nothing in an ETP or crypto universe.
• total counts every match; page through them with offset rather than raising limit past what you need.

Which error codes can List screener filters return?

List screener filters has no error codes of its own beyond the common ones.

Every operation can also return the common error codes listed in the reference.

Which plans include List screener filters?

List screener filters belongs to the Screening family of operations and counts as one research call against your plan's monthly allowance. Which families your plan includes, and how large its allowances are, is set out in What each plan includes.