---
title: "Describe a screener filter"
description: "Describe a screener filter returns one filter in full: its inputs, every relation and comparison target, the allowed values, the defaults and the units."
canonical_url: "https://fincanva.com/docs/api-mcp/describe-a-screener-filter"
last_updated: "2026-10-01"
md_url: "https://fincanva.com/docs/api-mcp/describe-a-screener-filter.md"
---

# Describe a screener filter

Returns one screener filter in full: what it measures, the inputs it takes (such as how many months or reports ago its value is read), every relation it supports (greater than, between, highest N, against the market or sector aggregate, against its own past), each relation's comparison targets with their allowed values and defaults, and the unit of every value.

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`](/docs/api-mcp/list-screener-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](/docs/api-mcp/fincanva-open-api-and-mcp-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`](/docs/api-mcp/units-and-conventions-in-the-fincanva-api-and-mcp#what-does-the-unit-native-mean))
- `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`](/docs/api-mcp/units-and-conventions-in-the-fincanva-api-and-mcp#what-does-the-unit-native-mean))
- `filter.inputs[].values.max` (number; unit: the unit of what it describes) — The largest value of a range. (convention [`native_unit`](/docs/api-mcp/units-and-conventions-in-the-fincanva-api-and-mcp#what-does-the-unit-native-mean))
- `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`](/docs/api-mcp/units-and-conventions-in-the-fincanva-api-and-mcp#what-does-the-unit-native-mean))
- `filter.inputs[].values.values` (list; unit: the unit of what it describes) — The accepted values of a list. (convention [`native_unit`](/docs/api-mcp/units-and-conventions-in-the-fincanva-api-and-mcp#what-does-the-unit-native-mean))
- `filter.inputs[].default` (number; unit: the unit of what it describes) — The value the screener proposes. (convention [`native_unit`](/docs/api-mcp/units-and-conventions-in-the-fincanva-api-and-mcp#what-does-the-unit-native-mean))
- `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`](/docs/api-mcp/units-and-conventions-in-the-fincanva-api-and-mcp#are-percentages-returned-as-fractions))
- `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`](/docs/api-mcp/units-and-conventions-in-the-fincanva-api-and-mcp#what-does-the-unit-native-mean))
- `filter.relations[].targets[].values.max` (number; unit: the unit of what it describes) — The largest value of a range. (convention [`native_unit`](/docs/api-mcp/units-and-conventions-in-the-fincanva-api-and-mcp#what-does-the-unit-native-mean))
- `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`](/docs/api-mcp/units-and-conventions-in-the-fincanva-api-and-mcp#what-does-the-unit-native-mean))
- `filter.relations[].targets[].values.values` (list; unit: the unit of what it describes) — The accepted values of a list. (convention [`native_unit`](/docs/api-mcp/units-and-conventions-in-the-fincanva-api-and-mcp#what-does-the-unit-native-mean))
- `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`](/docs/api-mcp/units-and-conventions-in-the-fincanva-api-and-mcp#what-does-the-unit-native-mean))
- `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?

```http
# 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:

```json
{
  "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](/docs/api-mcp/fincanva-open-api-and-mcp-reference#which-error-codes-can-a-fincanva-operation-return).

## 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](/docs/account-security/what-each-plan-includes).

Fincanva is for education and illustration only. It is not personalised financial advice, and past or simulated results do not predict future ones. [Read the Terms Addendum](https://fincanva.com/terms/addendum#section-3)