> ## Documentation Index
> Fetch the complete documentation index at: https://docs.qwairy.co/llms.txt
> Use this file to discover all available pages before exploring further.

# Compatibilité des filtres

> Contrat de filtres de référence et compatibilité outil par outil pour tous les outils MCP de Qwairy.

Cette page décrit le comportement des filtres dans le MCP client. La découverte des outils en direct (`tools/list`) fait foi pour l’inventaire actuel des outils et leurs schémas d’entrée. Un appel qui transmet un argument absent du schéma d’entrée de l’outil est rejeté avec l’erreur JSON-RPC `-32602`.

## Filtres globaux

Les paramètres suivants sont disponibles sur chaque outil listé dans la section **Outils à filtres globaux** ci-dessous.

| Paramètre | Type | Description |
| - | - | - |
| `period` | integer ou string | Nombre de jours glissants (1 à 3650), `"all"`, ou `"custom"` avec `startDate` et `endDate` |
| `startDate` | string | Date de début UTC incluse, au format `YYYY-MM-DD` |
| `endDate` | string | Date de fin UTC incluse, au format `YYYY-MM-DD` |
| `providers` | string\[] | Identifiants de fournisseurs ou de modèles IA ; les valeurs sont combinées par OU |
| `provider` | string | Ancien alias pour un seul fournisseur |
| `topicIds` | string\[] | UUID de Topics renvoyés par `list_topics` ; les valeurs sont combinées par OU |
| `topic` / `topicId` | string | Anciens alias pour un seul Topic |
| `tagIds` | string\[] | UUID de Tags renvoyés par `list_tags` ; les valeurs sont combinées par OU |
| `tag` / `tagId` | string | Anciens alias pour un seul Tag |
| `funnelStages` | string\[] | Parmi `TOFU`, `MOFU`, `BOFU` et `POST_PURCHASE` ; les valeurs sont combinées par OU |

Les valeurs d’un même tableau sont combinées par OU. Les différentes dimensions sont combinées par ET. Par exemple, deux fournisseurs, un Topic et un Tag signifient « l’un ou l’autre fournisseur, dans ce Topic, et avec ce Tag ».

Les dates personnalisées doivent être fournies par paire complète. Les deux bornes sont des jours calendaires UTC inclus. Les dates, UUID, valeurs de fournisseur et étapes du tunnel invalides, les plages incomplètes et les périodes non prises en charge renvoient `INVALID_PARAMETER`.

La plupart des outils d’analyse utilisent 30 jours par défaut. `get_competitors` conserve volontairement son résultat historique sur toute la période lorsqu’aucune fenêtre n’est fournie. Passez `period: 30` pour obtenir le même périmètre explicite de 30 jours que la plupart des vues du tableau de bord.

Lorsqu’un outil renvoie `appliedFilters`, cet objet reprend la période, les dates, les fournisseurs, les Topics, les Tags et les étapes du tunnel effectivement utilisés pour le résultat.

## Outils à filtres globaux

Les outils suivants prennent en charge l’intégralité du contrat de filtres globaux ci-dessus :

* `get_brand_performance`
* `get_competitors`
* `get_competitor_evolution`
* `get_prompts`
* `get_prompt_answers`
* `get_answers`
* `get_source_domains`
* `get_source_urls`
* `get_source_trends`
* `get_topics`
* `get_visibility_trend`
* `get_sentiment_trend`
* `get_provider_breakdown`
* `get_keyword_triggers`
* `get_content_opportunities`
* `get_competitor_comparison`
* `get_prompt_signals`
* `get_overview`
* `get_shopping_insights`
* `get_social_insights`
* `get_local_insights`
* `get_query_fan_out`
* `get_page_presence`
* `get_source_profile`
* `get_competitor_position`
* `get_matrix`
* `get_sponsored_content`
* `get_backlink_opportunities`

`get_follow_ups` utilise le même périmètre avec `period` (jours ou `"all"`), `startDate`/`endDate`, `providers`, `topicIds`, `tagIds` et `funnelStages`. Il n’accepte pas les anciens alias à valeur unique (`provider`, `topic`, `topicId`, `tag`, `tagId`).

Les sélecteurs propres à un outil, comme `relationship`, `competitorId`, `domain`, `type`, `isSelf`, `status`, `promptId`, `granularity`, `groupBy`, `limit` et `offset`, peuvent être combinés avec les filtres globaux lorsque l’outil les annonce.

## Filtres de persona et de pays

`get_prompts`, `get_answers`, `get_follow_ups` et `get_matrix` acceptent aussi :

| Paramètre | Type | Description |
| - | - | - |
| `personaIds` | string\[] | UUID des Personas enregistrées sur la réponse ; `"default"` correspond aux réponses générées sans Persona |
| `countries` | string\[] | Pays des réponses en codes ISO 3166-1 alpha-2, 50 au maximum. Les codes sont nettoyés, mis en majuscules et dédoublonnés ; un code invalide renvoie `INVALID_PARAMETER` ; un tableau vide n’applique aucun filtre |

Ces deux filtres utilisent la Persona et le pays enregistrés au moment où chaque réponse a été générée : une modification ultérieure de la configuration d’un prompt ne réécrit donc pas l’historique. Sur `get_prompts`, ils sélectionnent les prompts qui ont au moins une réponse historique correspondante ; les Personas renvoyées restent celles actuellement rattachées au prompt.

## Filtres du Centre d’actions

`get_actions` utilise le vocabulaire du Centre d’actions du tableau de bord :

| Paramètre | Type | Description |
| - | - | - |
| `period` | string | `"1"`, `"7"`, `"14"`, `"30"`, `"all"` ou `"custom"` |
| `periodStart` / `periodEnd` | string | Plage personnalisée incluse, utilisée avec `period: "custom"` |
| `providers` | string\[] | Identifiants des fournisseurs à l’origine des données |
| `topicIds` | string\[] | UUID de Topics |
| `tagIds` | string\[] | UUID de Tags |
| `funnelStages` | string\[] | `TOFU`, `MOFU`, `BOFU` ou `POST_PURCHASE` |
| `actionId`, `status`, `type`, `category` | string | Sélecteurs propres aux actions |
| `limit` | integer | Nombre maximal d’actions renvoyées (par défaut : 25, maximum : 100) |

## Filtres de dates de Measure

Les outils suivants prennent en charge `period`, `startDate`/`endDate` inclus et l’ancien paramètre `days` :

* `get_ai_revenue`
* `get_search_console_metrics`
* `get_bing_metrics`
* `get_referrer_analytics`

Utilisez `days` ou `period`, pas les deux. Un `period` numérique accepte 1 à 3650 ; l’ancien `days` accepte 1 à 365. Pour ces quatre outils liés à des fournisseurs connectés, `"all"` correspond à un historique de 16 mois. Les fenêtres glissantes et `"all"` se terminent la veille (jour UTC) ; les dates personnalisées utilisent exactement la plage incluse fournie.

`get_page_performance` utilise le même vocabulaire de dates, mais les données des crawlers par page sont conservées au plus 30 jours d’analyse. Les périodes numériques et plages personnalisées de plus de 30 jours renvoient `INVALID_PARAMETER` ; `period: "all"` désigne tout l’historique de pages conservé.

## Filtres et sélecteurs propres à un outil

Les outils suivants n’utilisent pas les filtres globaux sur les réponses :

| Outil | Filtres ou sélecteurs pris en charge |
| - | - |
| `list_brands` | Aucun |
| `list_pitch_audits` | `teamId`, `status`, `limit`, `offset` |
| `get_pitch_audit` | `auditId`, `subjectId`, `includeAnswers`, `includeCoCompetitorScores` |
| `list_topics` | `search`, `limit`, `offset` |
| `list_tags` | `search`, `limit`, `offset` |
| `get_answer_details` | `brandId`, `answerId` |
| `get_brand_perception` | Dernier instantané terminé pour `brandId` |
| `get_technical_status` | État technique actuel pour `brandId` |
| `get_perception_history` | `limit` |
| `get_crawler_activity` | Cycle de vie actuel des crawlers conservé pour `brandId` |
| `get_site_diagnostics` | `limit` |
| `search_documentation` | `query` sur la documentation publique |

Les outils d’instantané et de détail n’acceptent volontairement pas les filtres d’analyse : ils renvoient un enregistrement précis ou l’état le plus récent, et non un agrégat de réponses.

## Exemples

```json theme={null}
{
  "brandId": "brand-uuid",
  "period": 30,
  "providers": ["openai", "anthropic"],
  "topicIds": ["topic-uuid"],
  "tagIds": ["tag-uuid"],
  "funnelStages": ["BOFU"]
}
```

```json theme={null}
{
  "brandId": "brand-uuid",
  "startDate": "2026-08-01",
  "endDate": "2026-08-22",
  "tag": "tag-uuid"
}
```


This documentation is built and hosted on [Mintlify](https://mintlify.com), a developer documentation platform.