--- title: "List screener filters" description: "List screener filters searches the screener filter catalogue by name or investing concept and returns each filter with its level, category and relations." canonical_url: "https://fincanva.com/docs/api-mcp/list-screener-filters" last_updated: "2026-10-01" md_url: "https://fincanva.com/docs/api-mcp/list-screener-filters.md" --- # List screener filters Searches the screener's filter catalogue 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. Results come in catalogue order, a page at a time. 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`](/docs/api-mcp/describe-a-screener-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](/docs/api-mcp/fincanva-open-api-and-mcp-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? ```http # Caller on the free plan POST /api/v1/research/list_screen_filters Authorization: Bearer Content-Type: application/json { "concept": "value", "limit": 2 } ``` The result: ```json { "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](/docs/api-mcp/fincanva-open-api-and-mcp-reference#which-error-codes-can-a-fincanva-operation-return). ## 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](/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)