---
title: "Descrivi un filtro dello screener"
description: "Descrivi un filtro dello screener restituisce un filtro completo: input, ogni relazione e termine di confronto, valori ammessi, valori predefiniti e unità."
canonical_url: "https://fincanva.com/it/docs/api-e-mcp/descrivi-un-filtro-dello-screener"
last_updated: "2026-10-01"
md_url: "https://fincanva.com/it/docs/api-e-mcp/descrivi-un-filtro-dello-screener.md"
---

# Descrivi un filtro dello screener

Restituisce un filtro dello screener per intero: che cosa misura, gli input che accetta (come quanti mesi o bilanci prima viene letto il suo valore), ogni relazione che supporta (maggiore di, tra, i primi N, rispetto all’aggregato di mercato o di settore, rispetto al proprio passato), i termini di confronto di ciascuna relazione con i valori ammessi e quelli predefiniti, e l’unità di ogni valore.

Id dell’operazione: `describe_screen_filter` — REST `POST /api/v1/research/describe_screen_filter`, strumento MCP `describe_screen_filter`.

## Quando si usa Descrivi un filtro dello screener?

- Stai scrivendo una riga di screener e ti servono i valori esatti che un filtro accetta.
- L’utente chiede come si può confrontare un filtro, o qual è la sua soglia predefinita.

Usa un’altra operazione quando:

- Non conosci ancora l’id del filtro — usa invece [`list_screen_filters`](/it/docs/api-e-mcp/elenca-i-filtri-dello-screener).
- Hai scelto i filtri e vuoi che lo screener venga costruito — usa invece `create_screener`.

## Quali parametri accetta Descrivi un filtro dello screener?

- `id` (obbligatorio; testo) — L’id pubblico del filtro, come lo restituisce list_screen_filters.

## Che cosa restituisce Descrivi un filtro dello screener?

L’oggetto `result` contiene i campi qui sotto. Ogni risultato riporta anche un `summary` testuale, i valori `assumed` e la `dataVersion`, come descrive [il riferimento](/it/docs/api-e-mcp/riferimento-dell-open-api-e-del-server-mcp-di-fincanva).

- `filter` (oggetto) — Il filtro per intero.
- `filter.id` (testo) — L’id pubblico e stabile del filtro.
- `filter.name` (testo; almeno 1 caratteri) — Il nome del filtro come lo mostra lo screener.
- `filter.level` (testo; uno tra `asset`, `sector`, `market`) — `asset`, `sector` o `market`.
- `filter.category` (testo; uno tra `fundamental`, `technical`, `market_and_sector`) — `fundamental`, `technical` o `market_and_sector`.
- `filter.subcategory` (testo; almeno 1 caratteri) — La sottocategoria del catalogo, come Valuation Ratios.
- `filter.description` (testo; almeno 1 caratteri) — La descrizione del catalogo di che cosa misura il filtro.
- `filter.appliesTo` (elenco) — I tipi di asset a cui il filtro si applica.
- `filter.inputs` (elenco) — Le impostazioni che il filtro richiede prima del confronto, come quanti mesi o bilanci prima viene letto il suo valore.
- `filter.inputs[].id` (testo; uno tra `months_ago`, `reports_ago`, `months`, `days`, `quarters`, `bars`, `std_devs`) — `months_ago`, `reports_ago`, `months`, `days`, `quarters`, `bars` o `std_devs`.
- `filter.inputs[].name` (testo; almeno 1 caratteri) — Il nome dell’input come lo mostra lo screener.
- `filter.inputs[].description` (testo; almeno 1 caratteri) — Che cosa cambia l’input e l’unità in cui è contato.
- `filter.inputs[].unit` (testo; uno tra `none`, `number`, `count`, `days`, `weeks`, `months`, `quarters`, `years`, `reports`, `bars`, `fraction`, `percent`, `multiple`, `sharpe_points`, `sigma`, `usd`, `base_currency`, `date`, `native`) — L’unità dei valori dell’input. (convenzione [`native_unit`](/it/docs/api-e-mcp/unita-e-convenzioni-dell-open-api-e-del-server-mcp-di-fincanva#che-cosa-significa-lunità-native))
- `filter.inputs[].values` (oggetto) — I valori che l’input accetta.
- `filter.inputs[].values.kind` (testo; uno tra `range`) — `range` per valori equidistanti da `min` a `max`, `list` per un elenco esplicito.
- `filter.inputs[].values.min` (numero; unità: l’unità di ciò che descrive) — Il valore più piccolo di un intervallo. (convenzione [`native_unit`](/it/docs/api-e-mcp/unita-e-convenzioni-dell-open-api-e-del-server-mcp-di-fincanva#che-cosa-significa-lunità-native))
- `filter.inputs[].values.max` (numero; unità: l’unità di ciò che descrive) — Il valore più grande di un intervallo. (convenzione [`native_unit`](/it/docs/api-e-mcp/unita-e-convenzioni-dell-open-api-e-del-server-mcp-di-fincanva#che-cosa-significa-lunità-native))
- `filter.inputs[].values.step` (numero; maggiore di `0`; unità: l’unità di ciò che descrive) — La distanza tra i valori di un intervallo. (convenzione [`native_unit`](/it/docs/api-e-mcp/unita-e-convenzioni-dell-open-api-e-del-server-mcp-di-fincanva#che-cosa-significa-lunità-native))
- `filter.inputs[].values.values` (elenco; unità: l’unità di ciò che descrive) — I valori accettati di un elenco. (convenzione [`native_unit`](/it/docs/api-e-mcp/unita-e-convenzioni-dell-open-api-e-del-server-mcp-di-fincanva#che-cosa-significa-lunità-native))
- `filter.inputs[].default` (numero; unità: l’unità di ciò che descrive) — Il valore che lo screener propone. (convenzione [`native_unit`](/it/docs/api-e-mcp/unita-e-convenzioni-dell-open-api-e-del-server-mcp-di-fincanva#che-cosa-significa-lunità-native))
- `filter.relations` (elenco) — Ogni relazione che il filtro supporta, ciascuna con ciò a cui può essere confrontata.
- `filter.relations[].id` (testo; uno tra `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`) — L’id pubblico della relazione, come `greater_than`, `between`, `highest`, `crossing_above_within_days` o `undervalued`.
- `filter.relations[].label` (testo; almeno 1 caratteri) — L’etichetta della relazione nello screener, come `>` o `Between`.
- `filter.relations[].targets` (elenco) — A che cosa può essere confrontato il valore del filtro con questa relazione.
- `filter.relations[].targets[].kind` (testo; uno tra `value`) — `value` (un valore fisso), `range` (due valori), `count` (l’N di highest o lowest N), `market_aggregate` o `sector_aggregate` (una statistica del mercato o del settore), `own_past` (il valore precedente del filtro stesso) oppure `none` (la relazione non richiede un valore).
- `filter.relations[].targets[].unit` (testo; uno tra `none`, `number`, `count`, `days`, `weeks`, `months`, `quarters`, `years`, `reports`, `bars`, `fraction`, `percent`, `multiple`, `sharpe_points`, `sigma`, `usd`, `base_currency`, `date`, `native`) — L’unità dei valori del termine di confronto: `number` per un numero semplice, `fraction` per una percentuale (0.02 è il 2.0 % che mostra lo screener), `usd` per i dollari statunitensi. (convenzione [`fraction`](/it/docs/api-e-mcp/unita-e-convenzioni-dell-open-api-e-del-server-mcp-di-fincanva#le-percentuali-sono-restituite-come-frazioni))
- `filter.relations[].targets[].values` (oggetto) — I valori che il termine di confronto accetta.
- `filter.relations[].targets[].values.kind` (testo; uno tra `range`) — `range` o `list`, come per gli input.
- `filter.relations[].targets[].values.min` (numero; unità: l’unità di ciò che descrive) — Il valore più piccolo di un intervallo. (convenzione [`native_unit`](/it/docs/api-e-mcp/unita-e-convenzioni-dell-open-api-e-del-server-mcp-di-fincanva#che-cosa-significa-lunità-native))
- `filter.relations[].targets[].values.max` (numero; unità: l’unità di ciò che descrive) — Il valore più grande di un intervallo. (convenzione [`native_unit`](/it/docs/api-e-mcp/unita-e-convenzioni-dell-open-api-e-del-server-mcp-di-fincanva#che-cosa-significa-lunità-native))
- `filter.relations[].targets[].values.step` (numero; maggiore di `0`; unità: l’unità di ciò che descrive) — La distanza tra i valori di un intervallo. (convenzione [`native_unit`](/it/docs/api-e-mcp/unita-e-convenzioni-dell-open-api-e-del-server-mcp-di-fincanva#che-cosa-significa-lunità-native))
- `filter.relations[].targets[].values.values` (elenco; unità: l’unità di ciò che descrive) — I valori accettati di un elenco. (convenzione [`native_unit`](/it/docs/api-e-mcp/unita-e-convenzioni-dell-open-api-e-del-server-mcp-di-fincanva#che-cosa-significa-lunità-native))
- `filter.relations[].targets[].default` (numero; unità: l’unità di ciò che descrive) — Ciò che lo screener propone: un numero per `value`, una coppia per `range`, un conteggio per `count`, una statistica per un aggregato. (convenzione [`native_unit`](/it/docs/api-e-mcp/unita-e-convenzioni-dell-open-api-e-del-server-mcp-di-fincanva#che-cosa-significa-lunità-native))
- `filter.relations[].targets[].statistics` (elenco) — Le statistiche che un aggregato può usare: `average`, `median`, `p75`, `p25` e `index` dove l’aggregato è il livello di un indice.
- `filter.defaultRelation` (testo; uno tra `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`) — La relazione che lo screener propone per prima.

## Com’è fatta una chiamata a Descrivi un filtro dello screener?

### Tutti i modi in cui si può confrontare il filtro P/E

Domanda: Quali soglie di P/E può usare una riga dello screener?

```http
# Chiamante con il piano free
POST /api/v1/research/describe_screen_filter
Authorization: Bearer <chiave API o token di accesso>
Content-Type: application/json

{
  "id": "p_e"
}
```

Il risultato:

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

Il riepilogo restituito:

> P/E: an asset-level fundamental filter for stocks, with 1 input and 7 relations; the screener proposes between 0 and 15.

## Dove si sbaglia più spesso con Descrivi un filtro dello screener?

- I valori sono nell’unità che ogni termine di confronto indica — un numero semplice per il P/E, una frazione per una percentuale (0.02 è il 2 %), dollari statunitensi per la capitalizzazione di mercato. Un valore tra due di quelli elencati viene rifiutato, mai arrotondato.
- `highest` e `lowest` richiedono un conteggio, non una soglia: highest 5 tiene i cinque valori più alti tra quelli che le righe precedenti hanno lasciato passare.
- Un valore è letto alla data che l’input indica: `months_ago` 12 confronta il valore di un anno fa, non quello di oggi.

## Quali codici di errore restituisce Descrivi un filtro dello screener?

- `not_found` (HTTP 404) — Nessun filtro ha l’id che hai indicato. Soluzione: Cerca con list_screen_filters e usa un id che restituisce.

Ogni operazione può restituire anche i codici di errore comuni elencati nel [riferimento](/it/docs/api-e-mcp/riferimento-dell-open-api-e-del-server-mcp-di-fincanva#quali-codici-di-errore-può-restituire-unoperazione-di-fincanva).

## Quali piani includono Descrivi un filtro dello screener?

Descrivi un filtro dello screener appartiene alla famiglia di operazioni «Screening» e conta come una chiamata di ricerca nella quota mensile del tuo piano. Quali famiglie include il tuo piano, e quanto sono ampie le sue quote, lo trovi in [Cosa include ciascun piano](/it/docs/account-e-sicurezza/cosa-include-ciascun-piano).

Fincanva ha uno scopo solo educativo e illustrativo: non è una consulenza finanziaria personalizzata, e i risultati passati o simulati non indicano quelli futuri. [Leggi l'Addendum ai Termini](https://fincanva.com/it/terms/addendum#section-3)