Aller au contenu
Base de connaissances

Outils de vivier de répondants — référence des outils MCP

Les outils de vivier gèrent des groupes réutilisables de répondants destinés aux campagnes. Un vivier peut être créé à la main ou généré à partir d’une stratégie d’échantillonnage pour obtenir un échantillon représentatif. Les viviers générés par une stratégie suivent un score de qualité, enregistrent les paramètres de tirage avec lesquels ils ont été produits (taille demandée, facteur de suréchantillonnage, algorithme de sélection, exigence d’adresse e-mail, exclusions) et peuvent être actualisés avec ces mêmes réglages à mesure que la base de répondants évolue. La stratégie elle-même ne porte aucun paramètre de tirage : une même stratégie peut donc alimenter des viviers de tailles différentes.

Liste tous les viviers de répondants, avec un filtre facultatif par projet ou par nom.

Paramètre Type Obligatoire Par défaut Description
project_id string Non — Filtre par identifiant de projet
name string Non — Filtre par sous-chaîne, insensible à la casse
limit integer Non 100 Nombre maximal de résultats renvoyés

Renvoie : { data: [...], count, limit }. Chaque élément comporte source_type, source_strategy_id, respondent_count, quality_score et les cinq paramètres de tirage (requested_size, oversample_factor, selection_algorithm, require_email, exclude_respondent_ids) — tous à null pour un vivier sans tirage enregistré (viviers manuels, fusionnés ou scindés).


Récupère un vivier de répondants par son identifiant, avec la liste complète de ses répondants et le détail de sa qualité.

Paramètre Type Obligatoire Par défaut Description
pool_id string Oui — UUID du vivier

Renvoie : l’objet vivier complet avec id, name, description, project_id, source_type, source_strategy_id, respondent_ids, respondent_count, les cinq paramètres de tirage (requested_size, oversample_factor, selection_algorithm, require_email, exclude_respondent_ids ; null en l’absence de tirage enregistré), quality_score, quality_details, generated_at.

requested_size correspond à ce que le tirage a demandé ; respondent_count au nombre de membres effectifs du vivier. Les deux peuvent légitimement différer : suréchantillonnage, manque de répondants éligibles ou modifications manuelles ultérieures.


Crée un nouveau vivier de répondants (type de source manuel).

Paramètre Type Obligatoire Par défaut Description
name string Oui — Nom du vivier
description string Non — Description du vivier
project_id string Non — Projet de rattachement
respondent_ids string[] Non — Identifiants des répondants initiaux

Renvoie : { id, name, description, project_id, respondent_count }


Ajoute des répondants à un vivier existant. Les doublons sont ignorés sans avertissement.

Un vivier ne contient que les répondants de son propre projet : quiconque peut lire le vivier peut donc lire chacun de ses membres. Un répondant d’un autre projet est refusé, même si vous pouvez le lire. Dans une organisation qui partage son panel de répondants, ainsi que pour un vivier sans projet, n’importe quel répondant de l’organisation peut être ajouté.

Paramètre Type Obligatoire Par défaut Description
pool_id string Oui — UUID du vivier
respondent_ids string[] Oui — Identifiants des répondants à ajouter

Renvoie :

{
"pool_id": "...",
"added": 8,
"duplicates_skipped": 2,
"new_total": 50
}

Retire des répondants d’un vivier.

Paramètre Type Obligatoire Par défaut Description
pool_id string Oui — UUID du vivier
respondent_ids string[] Oui — Identifiants des répondants à retirer

Renvoie :

{
"pool_id": "...",
"removed": 3,
"not_found": 1,
"new_total": 47
}

Tire un nouveau vivier de répondants à partir d’une stratégie d’échantillonnage. L’algorithme de sélection retient les répondants correspondant aux distributions démographiques cibles de la stratégie. Les paramètres de tirage se transmettent à chaque appel et ne sont pas des propriétés de la stratégie ; le nouveau vivier les enregistre afin que chaque actualisation refasse le tirage de la même manière.

Paramètre Type Obligatoire Par défaut Description
strategy_id string Oui — UUID de la stratégie d’échantillonnage
pool_name string Oui — Nom du nouveau vivier
description string Non — Description du vivier
project_id string Non — Identifiant du projet. Par défaut, le projet de la stratégie
requested_size integer Oui — Nombre de répondants visé par ce tirage, avant suréchantillonnage (> 0)
oversample_factor float Non 1.0 Marge pour la non-réponse appliquée à requested_size (≥ 1 ; par ex. 1.2 = 20 % de plus)
selection_algorithm string Non "greedy" "greedy" ou "random_constrained"
require_email boolean Non false Seuls les répondants disposant d’une adresse e-mail sont éligibles
exclude_respondent_ids string[] Non [] UUID de répondants jamais éligibles pour ce tirage (par ex. une vague précédente)

Les paramètres invalides (une taille de 0, un suréchantillonnage inférieur à 1, un algorithme inconnu, une exclusion qui n’est pas un UUID de répondant) sont refusés avant la lecture du moindre répondant.

Le tirage ne prend en compte que les répondants du projet auquel appartient le nouveau vivier : un vivier n’intègre donc jamais de répondants que les autres propriétaires du projet ne peuvent pas voir. Il en va de même lors de l’actualisation du vivier, quelle que soit la personne qui l’actualise. Dans une organisation qui partage son panel de répondants, ainsi que pour un vivier sans projet, le tirage porte sur l’ensemble du panel.

Exemple :

{
"strategy_id": "...",
"pool_name": "Urban Millennials — main wave",
"requested_size": 200,
"oversample_factor": 1.2
}

Renvoie :

{
"pool_id": "...",
"pool_name": "Urban Millennials — main wave",
"strategy_id": "...",
"respondent_count": 240,
"requested_size": 200,
"effective_size": 240,
"quality_score": 0.94,
"quality_details": { },
"computation_time_ms": 145,
"warnings": []
}

effective_size vaut requested_size × oversample_factor (arrondi à l’entier inférieur) : c’est l’effectif visé par le tirage. Lorsque trop peu de répondants sont éligibles, le vivier compte moins de membres et warnings contient un message de déficit indiquant les deux tailles, par exemple Could not fill the draw: 90 of 120 drawn (requested 100 x oversample 1.2); only 90 candidates eligible.

Le vivier créé porte source_type: "strategy" et enregistre source_strategy_id ainsi que les paramètres de tirage, en vue d’une actualisation ultérieure. Pour tirer à une autre taille, générez un autre vivier à partir de la même stratégie.


Prévisualise la génération d’un vivier sans le créer. Exécute le même tirage que generate_pool_from_strategy et renvoie les métriques de qualité.

Paramètre Type Obligatoire Par défaut Description
strategy_id string Oui — UUID de la stratégie d’échantillonnage
project_id string Non — Projet auquel le vivier appartiendrait, comme pour generate_pool_from_strategy. Par défaut, le projet de la stratégie
max_preview integer Non 100 Nombre maximal d’identifiants de répondants inclus dans l’aperçu

L’outil accepte aussi les mêmes paramètres de tirage que generate_pool_from_strategy : requested_size (obligatoire), oversample_factor, selection_algorithm, require_email, exclude_respondent_ids.

Renvoie :

{
"eligible_count": 500,
"requested_size": 200,
"effective_size": 200,
"selected_count": 200,
"quality_score": 0.94,
"quality_details": { },
"sample_respondent_ids": ["..."],
"computation_time_ms": 130,
"warnings": []
}

Refait sur place le tirage d’un vivier généré par stratégie, à partir de la base de répondants actuelle. Ne fonctionne que pour les viviers portant source_type: "strategy". L’actualisation n’accepte aucun paramètre de tirage : elle refait le tirage avec la taille demandée, le facteur de suréchantillonnage, l’algorithme, l’exigence d’adresse e-mail et les exclusions enregistrés sur le vivier lors de sa génération, en s’appuyant sur les facteurs actuels de la stratégie. Pour changer la taille, générez un nouveau vivier et affectez-le à la campagne.

Paramètre Type Obligatoire Par défaut Description
pool_id string Oui — UUID du vivier (doit avoir été généré par stratégie)

Renvoie :

{
"pool_id": "...",
"previous_size": 195,
"new_size": 200,
"added": 10,
"removed": 5,
"requested_size": 200,
"effective_size": 200,
"quality_score": 0.96,
"quality_details": { },
"warnings": []
}

Supprime un vivier de répondants.

Paramètre Type Obligatoire Par défaut Description
pool_id string Oui — UUID du vivier

Renvoie : { pool_id, deleted }


Cas Réponse
Vivier introuvable {"error": "Pool {id} not found"}
Stratégie introuvable, ou située dans un projet que l’appelant ne peut pas lire (génération, aperçu) {"error": "Strategy {id} not found"}
Aucun répondant éligible {"error": "No eligible respondents available for this strategy"}
Vivier non généré par stratégie {"error": "Pool was not generated from a strategy — cannot refresh"}
Stratégie source supprimée, ou située dans un projet que l’appelant ne peut pas lire (actualisation) {"error": "Source strategy {id} not found"}
Vivier de stratégie sans tirage enregistré (actualisation) Conflit : le vivier n’a enregistré aucun paramètre de tirage et ne peut donc pas être actualisé. Générez plutôt un nouveau vivier à partir de la stratégie, à la taille souhaitée, et affectez-le à la campagne.
L’appelant n’est pas propriétaire du projet du vivier {"error": "forbidden", "detail": "caller is not an owner of this project and lacks an admin role"}

add_respondents_to_pool détecte les doublons par des opérations ensemblistes. Les doublons sont ignorés sans avertissement et comptabilisés dans duplicates_skipped — aucune erreur n’est levée.

Type de source Créé par Actualisable
"manual" create_respondent_pool Non
"strategy" generate_pool_from_strategy Oui, avec les paramètres de tirage enregistrés sur le vivier

Tout tirage (génération, aperçu, actualisation) part des répondants que vous pouvez voir : l’ensemble du panel dans une organisation privée ou pour un administrateur, sinon les répondants des projets dont vous êtes propriétaire. Cela vaut aussi pour la stratégie par défaut de l’organisation : un tirage ne désigne donc jamais un répondant que list_respondents ne vous montrerait pas.

Il les filtre ensuite avant la sélection, selon les paramètres du tirage :

  1. Si require_email est activé, les répondants sans adresse e-mail sont exclus
  2. Les répondants figurant dans exclude_respondent_ids sont exclus
  3. S’il ne reste aucun répondant éligible, la génération et l’actualisation renvoient une erreur (une actualisation ne vide jamais un vivier) ; l’aperçu indique eligible_count: 0

Un membre retiré à la main d’un vivier n’est pas ajouté à exclude_respondent_ids : la prochaine actualisation peut donc le tirer de nouveau.