---
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/developers/reference/list-screen-filters"
last_updated: "2026-10-05"
md_url: "https://fincanva.com/developers/reference/list-screen-filters.md"
---

# List screener filters

Searches the [screener](/glossary/screener)'s [filter catalogue](/glossary/filter-taxonomy) — 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](/glossary/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`](/developers/reference/describe-screen-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](/glossary/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.

## 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 result envelope](/developers/concepts/the-result-envelope) 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`, `options`, `short_selling`, `ownership`, `market_and_sector`) — `fundamental`, `technical`, `options`, `short_selling`, `ownership` or `market_and_sector`.
- `filters[].subcategory` (string; at least 1 characters; may be null) — The catalogue's subcategory, such as Valuation Ratios; null when the catalogue gives the filter none.
- `filters[].description` (string; at least 1 characters; may be null) — The catalogue's description of what the filter measures; null when the catalogue gives none.
- `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`; may be null) — The relation the screener proposes first for this filter; null when the catalogue proposes none.
- `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?

```bash
# Caller on the free plan
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}'
```

The answer:

```json
{
  "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
  }
}
```

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](/glossary/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?

- `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](/developers/open-api/errors-in-the-fincanva-open-api#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 plans include the MCP server and the Open API, and how large their allowances are, is set out in [Plans, quotas and limits](/developers/get-started/plans-quotas-and-limits).

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)