Unpublished — this page is visible on staging only and is not on the public site.

List screener filters

Q: 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, options, short_selling, ownership, market_and_sector) — fundamental, technical, options, short_selling, ownership 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; unit: a count; default 25) — How many filters to return in this page. offset (optional; integer; at least 0; unit: a count; default 0) — How many matching filters to skip, to read the next page.

Q: 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? The answer: 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

Q: Which error codes can List screener filters return?

engine_failed (HTTP 502) — Fincanva could not read the screener's filter catalogue from its engine, and had none from before. Fix: Try again in a minute. Every operation can also return the common error codes listed in Errors.

Q: 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 plans include the MCP server and the Open API, and how large their allowances are, is set out in Plans, quotas and limits.

POST/api/v1/research/list_screen_filters

Searches the screener's filter catalogue — the engine's own, read live — by words in a filter's name or description, by investing concept (value, momentum, quality and more), by level (asset, sector, market), by category or by asset type, and returns each match with the inputs it takes and the kinds of comparison it supports.

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

Parameters

What parameters does List screener filters take?

querystringOptional
1–80 characters
Words to look for, ignoring case, in each filter's name and description.
conceptstringOptional
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.
levelstringOptional
one of asset, sector, market
asset for filters on the instrument itself, sector for its sector's aggregate, market for the whole market's.
categorystringOptional
one of fundamental, technical, options, short_selling, ownership, market_and_sector
fundamental, technical, options, short_selling, ownership or market_and_sector.
assetTypestringOptional
one of stocks, etps, crypto
Only filters that apply to this asset type: stocks, etps or crypto.
limitintegerOptionalDefault 25
from 1 to 200 · unit: a count
How many filters to return in this page.
offsetintegerOptionalDefault 0
at least 0 · unit: a count
How many matching filters to skip, to read the next page.

Show the code

Request

curl -X POST https://app.fincanva.com/api/v1/research/\
list_screen_filters \
  -H "Authorization: Bearer $FINCANVA_API_KEY" \
  -H "Content-Type: application/json" \
  -d '{"concept":"value","limit":2}'

import os

import requests

response = requests.post(
    "https://app.fincanva.com/api/v1/research/list_screen_filters",
    headers={"Authorization": f"Bearer {os.environ['FINCANVA_API_KEY']}"},
    json={
        "concept": "value",
        "limit": 2,
    },
)
body = response.json()

const response = await fetch("https://app.fincanva.com/api/v1/research/list_screen_filters", {
  method: "POST",
  headers: { Authorization: `Bearer ${process.env.FINCANVA_API_KEY}`, "Content-Type": "application/json" },
  body: JSON.stringify({
    "concept": "value",
    "limit": 2
  }),
});
const body = await response.json();

{
  "jsonrpc": "2.0",
  "id": 1,
  "method": "tools/call",
  "params": {
    "name": "list_screen_filters",
    "arguments": {
      "concept": "value",
      "limit": 2
    }
  }
}

Response

{
  "status": true,
  "data": {
    "result": {
      "filters": [
        { … },
        …
      ],
      "total": 9,
      "offset": 0,
      "limit": 2
    },
    "summary": "9 filters match the concept value;…",
    "assumed": [
      { … }
    ],
    "dataVersion": null
  }
}

{
  "type": "object",
  "properties": {
    "filters": {
      "type": "array",
      "items": {
        "type": "object",
        "properties": {
          "id": {
            "type": "string",
            "pattern": "^[a-z][a-z0-9]*(?:_[a-z0-9]+)*$"
          },
          "name": {
            "type": "string",
            "minLength": 1
          },
          "level": {
            "type": "string",
            "enum": [
              "asset",
              "sector",
              "market"
            ]
          },
          "category": {
            "type": "string",
            "enum": [
              "fundamental",
              "technical",
              "options",
              "short_selling",
              "ownership",
              "market_and_sector"
            ]
          },
          "subcategory": {
            "anyOf": [
              {
                "type": "string",
                "minLength": 1
              },
              {
                "type": "null"
              }
            ]
          },
          "description": {
            "anyOf": [
              {
                "type": "string",
                "minLength": 1
              },
              {
                "type": "null"
              }
            ]
          },
          "appliesTo": {
            "minItems": 1,
            "type": "array",
            "items": {
              "type": "string",
              "enum": [
                "stocks",
                "etps",
                "crypto"
              ]
            }
          },
          "inputs": {
            "type": "array",
            "items": {
              "type": "string",
              "enum": [
                "months_ago",
                "reports_ago",
                "months",
                "days",
                "quarters",
                "bars",
                "std_devs"
              ]
            }
          },
          "relations": {
            "minItems": 1,
            "type": "array",
            "items": {
              "type": "string",
              "enum": [
                "compare_to_value",
                "between",
                "highest_lowest",
                "compare_to_aggregate",
                "compare_to_own_past",
                "special"
              ]
            }
          },
          "defaultRelation": {
            "anyOf": [
              {
                "type": "string",
                "enum": [
                  "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"
                ]
              },
              {
                "type": "null"
              }
            ]
          }
        },
        "required": [
          "id",
          "name",
          "level",
          "category",
          "subcategory",
          "description",
          "appliesTo",
          "inputs",
          "relations",
          "defaultRelation"
        ],
        "additionalProperties": false
      }
    },
    "total": {
      "type": "integer",
      "minimum": 0,
      "maximum": 9007199254740991
    },
    "offset": {
      "type": "integer",
      "minimum": 0,
      "maximum": 9007199254740991
    },
    "limit": {
      "type": "integer",
      "minimum": 1,
      "maximum": 9007199254740991
    }
  },
  "required": [
    "filters",
    "total",
    "offset",
    "limit"
  ],
  "additionalProperties": false
}

Response

unauthorized

{
  "type": "object",
  "required": [
    "status",
    "message",
    "code"
  ],
  "properties": {
    "status": {
      "const": false
    },
    "message": {
      "type": "string",
      "description": "Written for an AI or a developer to act on."
    },
    "code": {
      "type": "string",
      "enum": [
        "unauthorized"
      ]
    },
    "details": {
      "description": "What the code needs to be acted on, such as the fields of an invalid input."
    }
  }
}

Response

plan_limit

{
  "type": "object",
  "required": [
    "status",
    "message",
    "code"
  ],
  "properties": {
    "status": {
      "const": false
    },
    "message": {
      "type": "string",
      "description": "Written for an AI or a developer to act on."
    },
    "code": {
      "type": "string",
      "enum": [
        "plan_limit"
      ]
    },
    "details": {
      "description": "What the code needs to be acted on, such as the fields of an invalid input."
    }
  }
}

Response

invalid_input

{
  "type": "object",
  "required": [
    "status",
    "message",
    "code"
  ],
  "properties": {
    "status": {
      "const": false
    },
    "message": {
      "type": "string",
      "description": "Written for an AI or a developer to act on."
    },
    "code": {
      "type": "string",
      "enum": [
        "invalid_input"
      ]
    },
    "details": {
      "description": "What the code needs to be acted on, such as the fields of an invalid input."
    }
  }
}

Response

quota_exhausted · rate_limited

{
  "type": "object",
  "required": [
    "status",
    "message",
    "code"
  ],
  "properties": {
    "status": {
      "const": false
    },
    "message": {
      "type": "string",
      "description": "Written for an AI or a developer to act on."
    },
    "code": {
      "type": "string",
      "enum": [
        "quota_exhausted",
        "rate_limited"
      ]
    },
    "details": {
      "description": "What the code needs to be acted on, such as the fields of an invalid input."
    }
  }
}

Response

engine_failed

{
  "type": "object",
  "required": [
    "status",
    "message",
    "code"
  ],
  "properties": {
    "status": {
      "const": false
    },
    "message": {
      "type": "string",
      "description": "Written for an AI or a developer to act on."
    },
    "code": {
      "type": "string",
      "enum": [
        "engine_failed"
      ]
    },
    "details": {
      "description": "What the code needs to be acted on, such as the fields of an invalid input."
    }
  }
}

Full response →

Response

What does List screener filters return?

filterslist
The matching filters, in catalogue order.
Show the 10 fields
- idstring
  The filter's stable public id — pass it to describe_screen_filter and to screener rows.
- 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 inputs the filter takes, by input id — how many months or reports ago its value is read, or the window it is measured over.
- relationslist
  The kinds of comparison the filter supports: compare_to_value, between, highest_lowest, compare_to_aggregate, compare_to_own_past, special.
- 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 for this filter; null when the catalogue proposes none.
totalinteger
at least 0 · unit: a count
How many filters matched in all.
offsetinteger
at least 0 · unit: a count
How many matching filters were skipped.
limitinteger
at least 1 · unit: a count
The most filters this page could hold.

Every response arrives inside the result envelope every operation shares.

Errors

Which error codes can List screener filters return?

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

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

What does a call to List screener filters look like?

The first two value filters

What filters can I use to find cheap stocks?

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

Full response · 200

{
  "status": true,
  "data": {
    "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
    },
    "summary": "9 filters match the concept value; showing the first 2: P/E (Positive) and P/E.",
    "assumed": [
      {
        "field": "/offset",
        "value": 0,
        "reason": "no offset was given, so the list starts at the first match"
      }
    ],
    "dataVersion": null
  }
}

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 plans include List screener filters?

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