Filtrage par handles X

Cibler des comptes spécifiques sur X

Comme Web Search permet de filtrer par domaines, X Search permet de filtrer par comptes (handles). Vous pouvez restreindre la recherche aux posts d’un ensemble de comptes spécifiques, ou au contraire exclure certains comptes des résultats. Ce filtrage est essentiel pour des cas d’usage de veille, de monitoring de marque ou d’analyse d’influenceurs.

Les deux paramètres de filtrage

X Search propose deux paramètres de filtrage par handles :

• allowed_x_handles : limite la recherche aux posts des comptes listés (liste blanche)
• excluded_x_handles : exclut les posts des comptes listés (liste noire)

Comme pour Web Search, ces paramètres sont mutuellement exclusifs. Vous ne pouvez pas les utiliser ensemble dans la même requête.

Chaque paramètre accepte un tableau de 10 handles maximum (contre 5 domaines pour Web Search).

Utiliser allowed_x_handles (liste blanche)

Ce paramètre est idéal pour surveiller les communications de comptes spécifiques :

response = client.responses.create(
    model="grok-4.20-reasoning",
    input="Quelles sont les dernières annonces de xAI ?",
    tools=[{
        "type": "x_search",
        "allowed_x_handles": ["@xaboratory", "@xaboratorydev"]
    }]
)

Le modèle ne recherchera que les posts publiés par ces comptes.

Cas d’usage de la liste blanche

• Veille concurrentielle : surveiller les annonces de vos concurrents
• Monitoring de marque : suivre vos comptes officiels et ceux de vos ambassadeurs
• Analyse d’influenceurs : agréger les opinions d’un panel d’experts
• Suivi institutionnel : suivre les comptes de régulateurs ou d’organisations officielles

Utiliser excluded_x_handles (liste noire)

Ce paramètre permet d’exclure certains comptes, par exemple les bots ou les comptes non pertinents :

response = client.responses.create(
    model="grok-4.20-reasoning",
    input="Que pensent les développeurs de la dernière version de Python ?",
    tools=[{
        "type": "x_search",
        "excluded_x_handles": ["@bot_python_news", "@spam_account"]
    }]
)

Cas d’usage de la liste noire

• Exclure les bots : éliminer les comptes automatisés des résultats
• Exclure le spam : filtrer les comptes connus pour le contenu de faible qualité
• Exclure vos propres comptes : analyser les réactions externes sans vos propres publications

Syntaxe par SDK

xAI SDK (Python)

from xai_sdk.tools import x_search

tools=[x_search(
    allowed_x_handles=["@elonmusk", "@xaboratory"]
)]

OpenAI SDK (Python)

tools=[{
    "type": "x_search",
    "allowed_x_handles": ["@elonmusk", "@xaboratory"]
}]

Vercel AI SDK (JavaScript)

tools: [xai.tools.xSearch({
  allowedXHandles: ["@elonmusk", "@xaboratory"]
})]

Notez la convention camelCase dans le SDK JavaScript : allowedXHandles au lieu de allowed_x_handles.

Bonnes pratiques

Choisir entre liste blanche et liste noire

Utilisez la liste blanche quand vous avez un périmètre de comptes défini et que vous ne voulez que leurs publications. C’est la méthode la plus précise et la plus économique en tokens.

Utilisez la liste noire quand vous voulez une recherche large mais propre, en éliminant les sources de bruit identifiées.

Optimiser le nombre de handles

Avec une limite de 10 handles, soyez sélectif. Si vous avez besoin de surveiller plus de 10 comptes, regroupez vos requêtes par thématique ou effectuez plusieurs appels séquentiels.

Format des handles

Les handles incluent le symbole @ (par exemple @xaboratory). Vérifiez que les handles sont corrects — un handle mal orthographié ne générera simplement aucun résultat pour ce compte.

Points clés à retenir

• Deux paramètres : allowed_x_handles (liste blanche) et excluded_x_handles (liste noire)
• Mutuellement exclusifs : un seul à la fois par requête
• Maximum 10 handles par paramètre
• Les handles incluent le @ : "@elonmusk", pas "elonmusk"
• Idéal pour la veille, le monitoring de marque et l’analyse d’influenceurs