Developers
Log inStart building
Unpublished — this page is visible on staging only and is not on the public site.
View .mdENIT

Describe a screener filter

POST/api/v1/research/describe_screen_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.

Authentication
REST: an API key or an OAuth access token. MCP: an OAuth access token.
MCP tool
describe_screen_filter
Cost
one research call

Parameters

What parameters does Describe a screener filter take?

  • idstringRequired

    The filter's public id, as list_screen_filters returns it.

Response

What does Describe a screener filter return?

  • filterobject

    The filter in full.

    Show the 10 fields
    • idstring

      The filter's stable public id.

    • namestring

      at least 1 characters

      The filter's name as the screener shows it.

    • levelstring

      one of asset, sector, market

      asset, sector or market.

    • categorystring

      one of fundamental, technical, options, short_selling, ownership, market_and_sector

      fundamental, technical, options, short_selling, ownership or market_and_sector.

    • subcategorystring

      at least 1 characters · may be null

      The catalogue's subcategory, such as Valuation Ratios; null when the catalogue gives the filter none.

    • descriptionstring

      at least 1 characters · may be null

      The catalogue's description of what the filter measures; null when the catalogue gives none.

    • appliesTolist

      The asset types the filter applies to.

    • inputslist

      The settings the filter takes before it is compared, such as how many months or reports ago its value is read.

      Show the 6 fields
      • idstring

        one of months_ago, reports_ago, months, days, quarters, bars, std_devs

        months_ago, reports_ago, months, days, quarters, bars or std_devs.

      • namestring

        at least 1 characters

        The input's name as the screener shows it.

      • descriptionstring

        at least 1 characters

        What the input changes and the unit it is counted in.

      • unitstring

        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

      • valuesobject

        The values the input accepts.

        Show the 5 fields
        • kindstring

          one of range

          range for evenly spaced values from min to max, list for an explicit list.

        • minnumber

          unit: the unit of what it describes

          The smallest value of a range. Convention: native_unit

        • maxnumber

          unit: the unit of what it describes

          The largest value of a range. Convention: native_unit

        • stepnumber

          greater than 0 · unit: the unit of what it describes

          The spacing between the values of a range. Convention: native_unit

        • valueslist

          unit: the unit of what it describes

          The accepted values of a list. Convention: native_unit

      • defaultnumber

        unit: the unit of what it describes

        The value the screener proposes. Convention: native_unit

    • relationslist

      Every relation the filter supports, each with what it can be compared to.

      Show the 3 fields
      • idstring

        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.

      • labelstring

        at least 1 characters

        The relation's label in the screener, such as > or Between.

      • targetslist

        What the filter's value can be compared to under this relation.

        Show the 5 fields
        • kindstring

          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).

        • unitstring

          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

        • valuesobject

          The values the target accepts.

          Show the 5 fields
          • kindstring

            one of range

            range or list, as for inputs.

          • minnumber

            unit: the unit of what it describes

            The smallest value of a range. Convention: native_unit

          • maxnumber

            unit: the unit of what it describes

            The largest value of a range. Convention: native_unit

          • stepnumber

            greater than 0 · unit: the unit of what it describes

            The spacing between the values of a range. Convention: native_unit

          • valueslist

            unit: the unit of what it describes

            The accepted values of a list. Convention: native_unit

        • defaultnumber

          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

        • statisticslist

          The statistics an aggregate target can use: average, median, p75, p25, and index where the aggregate is an index level.

    • defaultRelationstring

      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 · may be null

      The relation the screener proposes first; null when the catalogue proposes none, and then every row of the filter names its relation.

Every response arrives inside the result envelope every operation shares.

Errors

Which error codes can Describe a screener filter return?

  • not_found HTTP 404

    No filter has the id you gave. Search with list_screen_filters and use an id it returns.

  • engine_failed HTTP 502

    Fincanva could not read the screener's filter catalogue from its engine, and had none from before. Try again in a minute.

Common to every operation

  • unauthorized HTTP 401
  • plan_limit HTTP 403
  • invalid_input HTTP 422
  • quota_exhausted HTTP 429
  • rate_limited HTTP 429

Every error code

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.
  • You do not know the filter's id yet — Use instead list_screen_filters
  • You have chosen the filters and want the screener built — Use instead create_screener

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

Every way the P/E filter can be compared

What P/E thresholds can a screener row use?

P/E: an asset-level fundamental filter for stocks, with 1 input and 7 relations; the screener proposes between 0 and 15.
Full response · 200
{
  "status": true,
  "data": {
    "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"
      }
    },
    "summary": "P/E: an asset-level fundamental filter for stocks, with 1 input and 7 relations; the screener proposes between 0 and 15.",
    "assumed": [],
    "dataVersion": null
  }
}

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 plans include Describe a screener filter?

Family: Screening · Quota cost: one research call — Availability

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

DOCS · EN — IT