Describe a screener filter

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

When should you use Describe a screener filter?

• You are writing a screener row and need the exact values a filter accepts.
• The user asks how a filter can be compared, or what its default threshold is.

Use another operation when:

• You do not know the filter's id yet — use list_screen_filters instead.
• You have chosen the filters and want the screener built — use create_screener instead.

What parameters does Describe a screener filter take?

• id (required; string) — The filter's public id, as list_screen_filters returns it.

What does Describe a screener filter 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.

• filter (object) — The filter in full.
• filter.id (string) — The filter's stable public id.
• filter.name (string; at least 1 characters) — The filter's name as the screener shows it.
• filter.level (string; one of asset, sector, market) — asset, sector or market.
• filter.category (string; one of fundamental, technical, market_and_sector) — fundamental, technical or market_and_sector.
• filter.subcategory (string; at least 1 characters) — The catalogue's subcategory, such as Valuation Ratios.
• filter.description (string; at least 1 characters) — The catalogue's description of what the filter measures.
• filter.appliesTo (list) — The asset types the filter applies to.
• filter.inputs (list) — The settings the filter takes before it is compared, such as how many months or reports ago its value is read.
• filter.inputs[].id (string; one of months_ago, reports_ago, months, days, quarters, bars, std_devs) — months_ago, reports_ago, months, days, quarters, bars or std_devs.
• filter.inputs[].name (string; at least 1 characters) — The input's name as the screener shows it.
• filter.inputs[].description (string; at least 1 characters) — What the input changes and the unit it is counted in.
• filter.inputs[].unit (string; one of none, number, count, days, weeks, months, quarters, years, reports, bars, fraction, percent, multiple, sharpe_points, sigma, usd, base_currency, date, native) — The unit of the input's values. (convention native_unit)
• filter.inputs[].values (object) — The values the input accepts.
• filter.inputs[].values.kind (string; one of range) — range for evenly spaced values from min to max, list for an explicit list.
• filter.inputs[].values.min (number; unit: the unit of what it describes) — The smallest value of a range. (convention native_unit)
• filter.inputs[].values.max (number; unit: the unit of what it describes) — The largest value of a range. (convention native_unit)
• filter.inputs[].values.step (number; greater than 0; unit: the unit of what it describes) — The spacing between the values of a range. (convention native_unit)
• filter.inputs[].values.values (list; unit: the unit of what it describes) — The accepted values of a list. (convention native_unit)
• filter.inputs[].default (number; unit: the unit of what it describes) — The value the screener proposes. (convention native_unit)
• filter.relations (list) — Every relation the filter supports, each with what it can be compared to.
• filter.relations[].id (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's public id, such as greater_than, between, highest, crossing_above_within_days or undervalued.
• filter.relations[].label (string; at least 1 characters) — The relation's label in the screener, such as > or Between.
• filter.relations[].targets (list) — What the filter's value can be compared to under this relation.
• filter.relations[].targets[].kind (string; one of value) — value (a fixed value), range (two values), count (the N of highest or lowest N), market_aggregate or sector_aggregate (a statistic of the market or the sector), own_past (the filter's own earlier value) or none (the relation needs no value).
• filter.relations[].targets[].unit (string; one of none, number, count, days, weeks, months, quarters, years, reports, bars, fraction, percent, multiple, sharpe_points, sigma, usd, base_currency, date, native) — The unit of the target's values: number for a plain number, fraction for a percentage (0.02 is the 2.0 % the screener shows), usd for US dollars. (convention fraction)
• filter.relations[].targets[].values (object) — The values the target accepts.
• filter.relations[].targets[].values.kind (string; one of range) — range or list, as for inputs.
• filter.relations[].targets[].values.min (number; unit: the unit of what it describes) — The smallest value of a range. (convention native_unit)
• filter.relations[].targets[].values.max (number; unit: the unit of what it describes) — The largest value of a range. (convention native_unit)
• filter.relations[].targets[].values.step (number; greater than 0; unit: the unit of what it describes) — The spacing between the values of a range. (convention native_unit)
• filter.relations[].targets[].values.values (list; unit: the unit of what it describes) — The accepted values of a list. (convention native_unit)
• filter.relations[].targets[].default (number; unit: the unit of what it describes) — What the screener proposes: a number for value, a pair for range, a count for count, a statistic for an aggregate. (convention native_unit)
• filter.relations[].targets[].statistics (list) — The statistics an aggregate target can use: average, median, p75, p25, and index where the aggregate is an index level.
• filter.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.

What does a call to Describe a screener filter look like?

Every way the P/E filter can be compared

Asked as: What P/E thresholds can a screener row use?

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

{
  "id": "p_e"
}

The result:

{
  "filter": {
    "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": [
      {
        "id": "months_ago",
        "name": "Months Ago",
        "description": "Lag allows you to reference a value from the past.",
        "unit": "months",
        "values": {
          "kind": "list",
          "values": [
            0,
            1,
            2,
            3,
            6,
            12,
            24
          ]
        },
        "default": 0
      }
    ],
    "relations": [
      {
        "id": "greater_than",
        "label": ">",
        "targets": [
          {
            "kind": "value",
            "unit": "number",
            "values": {
              "kind": "range",
              "min": -20,
              "max": 100,
              "step": 0.5
            },
            "default": 12
          },
          {
            "kind": "market_aggregate",
            "statistics": [
              "average",
              "median",
              "p75",
              "p25"
            ],
            "default": "average"
          },
          {
            "kind": "sector_aggregate",
            "statistics": [
              "average",
              "median",
              "p75",
              "p25"
            ],
            "default": "average"
          },
          {
            "kind": "own_past"
          }
        ]
      },
      {
        "id": "less_than",
        "label": "<",
        "targets": [
          {
            "kind": "value",
            "unit": "number",
            "values": {
              "kind": "range",
              "min": -20,
              "max": 100,
              "step": 0.5
            },
            "default": 12
          },
          {
            "kind": "market_aggregate",
            "statistics": [
              "average",
              "median",
              "p75",
              "p25"
            ],
            "default": "average"
          },
          {
            "kind": "sector_aggregate",
            "statistics": [
              "average",
              "median",
              "p75",
              "p25"
            ],
            "default": "average"
          },
          {
            "kind": "own_past"
          }
        ]
      },
      {
        "id": "greater_or_equal",
        "label": ">=",
        "targets": [
          {
            "kind": "value",
            "unit": "number",
            "values": {
              "kind": "range",
              "min": -20,
              "max": 100,
              "step": 0.5
            },
            "default": 12
          },
          {
            "kind": "market_aggregate",
            "statistics": [
              "average",
              "median",
              "p75",
              "p25"
            ],
            "default": "average"
          },
          {
            "kind": "sector_aggregate",
            "statistics": [
              "average",
              "median",
              "p75",
              "p25"
            ],
            "default": "average"
          },
          {
            "kind": "own_past"
          }
        ]
      },
      {
        "id": "less_or_equal",
        "label": "<=",
        "targets": [
          {
            "kind": "value",
            "unit": "number",
            "values": {
              "kind": "range",
              "min": -20,
              "max": 100,
              "step": 0.5
            },
            "default": 12
          },
          {
            "kind": "market_aggregate",
            "statistics": [
              "average",
              "median",
              "p75",
              "p25"
            ],
            "default": "average"
          },
          {
            "kind": "sector_aggregate",
            "statistics": [
              "average",
              "median",
              "p75",
              "p25"
            ],
            "default": "average"
          },
          {
            "kind": "own_past"
          }
        ]
      },
      {
        "id": "between",
        "label": "Between",
        "targets": [
          {
            "kind": "range",
            "unit": "number",
            "values": {
              "kind": "range",
              "min": -20,
              "max": 100,
              "step": 0.5
            },
            "default": [
              0,
              15
            ]
          }
        ]
      },
      {
        "id": "highest",
        "label": "Highest",
        "targets": [
          {
            "kind": "count",
            "values": {
              "kind": "list",
              "values": [
                1,
                2,
                3,
                4,
                5,
                6,
                7,
                8,
                9,
                10,
                11,
                12,
                13,
                14,
                15,
                20,
                25,
                30,
                35,
                40,
                50,
                60,
                70,
                80,
                90,
                100,
                120,
                140,
                160,
                180,
                200,
                250,
                300
              ]
            },
            "default": 5
          }
        ]
      },
      {
        "id": "lowest",
        "label": "Lowest",
        "targets": [
          {
            "kind": "count",
            "values": {
              "kind": "list",
              "values": [
                1,
                2,
                3,
                4,
                5,
                6,
                7,
                8,
                9,
                10,
                11,
                12,
                13,
                14,
                15,
                20,
                25,
                30,
                35,
                40,
                50,
                60,
                70,
                80,
                90,
                100,
                120,
                140,
                160,
                180,
                200,
                250,
                300
              ]
            },
            "default": 5
          }
        ]
      }
    ],
    "defaultRelation": "between"
  }
}

The summary it returns:

P/E: an asset-level fundamental filter for stocks, with 1 input and 7 relations; the screener proposes between 0 and 15.

What goes wrong most often with Describe a screener filter?

• Values are in the unit each target states — a plain number for P/E, a fraction for a percentage (0.02 is 2 %), US dollars for market cap. A value between two listed ones is refused, never rounded.
• highest and lowest take a count, not a threshold: highest 5 keeps the five largest values among what the earlier rows kept.
• A value is read as of the input's lag: months_ago 12 compares the value of a year ago, not today's.

Which error codes can Describe a screener filter return?

• not_found (HTTP 404) — No filter has the id you gave. Fix: Search with list_screen_filters and use an id it returns.

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

Which plans include Describe a screener filter?

Describe a screener filter 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.