X Search pour le Marketing : Handles, Dates et Filtres

Transformer X en outil de veille marketing

X (anciennement Twitter) reste l’une des plateformes les plus riches en données marketing exploitables en temps réel. Avec l’outil x_search de l’API Grok, vous pouvez interroger cette masse d’informations de manière structurée, filtrée et automatisable, directement depuis vos applications ou scripts.

Contrairement à une recherche manuelle sur X, l’API vous permet de cibler précisément des comptes, des périodes et des thématiques. Pour un responsable marketing, cela signifie passer de la veille artisanale à un système de collecte d’intelligence concurrentielle programmable.

Activer X Search dans l’API Grok

L’outil x_search s’active en le déclarant dans le tableau tools de votre requête API. Il fonctionne exclusivement sur l’API Responses (l’ancien endpoint Chat Completions est déprécié pour la recherche).

from openai import OpenAI

client = OpenAI(
    api_key="votre-cle-xai",
    base_url="https://api.x.ai/v1"
)

response = client.responses.create(
    model="grok-4.20-reasoning",
    input="Quels sont les derniers posts de @nike sur leurs campagnes marketing ?",
    tools=[{"type": "x_search"}]
)

Le modèle décide automatiquement quand lancer une recherche sur X en fonction de votre question. Vous n’avez pas à gérer le déclenchement manuellement.

Filtrer par handles : cibler des comptes précis

Le paramètre allowed_x_handles vous permet de restreindre la recherche à un maximum de 10 comptes X spécifiques. C’est l’outil idéal pour surveiller vos concurrents directs ou vos partenaires.

response = client.responses.create(
    model="grok-4.20-reasoning",
    input="Résume les annonces produit de ces marques cette semaine",
    tools=[{
        "type": "x_search",
        "allowed_x_handles": [
            "@nike", "@adidas", "@puma",
            "@newbalance", "@reebok"
        ]
    }]
)

À l’inverse, excluded_x_handles permet d’exclure jusqu’à 10 comptes des résultats. Attention : ces deux paramètres sont mutuellement exclusifs (vous ne pouvez pas les combiner dans la même requête).

Cas d’usage marketing

• Veille concurrentielle : surveiller les 5-10 comptes de vos concurrents directs
• Partenariats : suivre les publications de vos partenaires et ambassadeurs
• Écosystème : exclure vos propres comptes pour ne voir que le marché

Filtrer par dates : isoler une période

Les paramètres from_date et to_date acceptent des dates au format ISO 8601 (YYYY-MM-DD). Vous pouvez ainsi cibler une campagne spécifique, un événement sectoriel ou comparer deux périodes.

response = client.responses.create(
    model="grok-4.20-reasoning",
    input="Analyse les réactions à la campagne Black Friday de ces marques",
    tools=[{
        "type": "x_search",
        "allowed_x_handles": ["@amazon_fr", "@cdiscount", "@fnac"],
        "from_date": "2025-11-25",
        "to_date": "2025-12-02"
    }]
)

Cette combinaison handles + dates vous donne un périmètre de recherche extrêmement précis, comparable à un brief d’étude de marché automatisé.

Comprendre les images et vidéos des posts

Deux paramètres booléens enrichissent votre veille visuelle :

• enable_image_understanding : le modèle analyse les images contenues dans les posts (visuels de campagne, infographies, captures d’écran)
• enable_video_understanding : le modèle interprète les vidéos (spots publicitaires, teasers produit, démonstrations)

tools=[{
    "type": "x_search",
    "allowed_x_handles": ["@apple"],
    "enable_image_understanding": True,
    "enable_video_understanding": True
}]

Pour un marketeur, cela signifie que Grok peut décrire les visuels publicitaires de vos concurrents, identifier les codes couleur utilisés, ou résumer le contenu d’une vidéo promotionnelle, le tout programmatiquement.

Mise en pratique : script de veille hebdomadaire

Voici un script complet qui génère un rapport de veille hebdomadaire sur vos concurrents :

from datetime import datetime, timedelta

# Calculer la semaine écoulée
today = datetime.now().strftime("%Y-%m-%d")
last_week = (datetime.now() - timedelta(days=7)).strftime("%Y-%m-%d")

response = client.responses.create(
    model="grok-4.20-reasoning",
    input="""Analyse les publications de ces marques sur la dernière semaine.
    Pour chaque marque, identifie :
    1. Les annonces produit majeures
    2. Les campagnes marketing lancées
    3. Le ton et le positionnement utilisé
    4. Les posts ayant généré le plus d'engagement""",
    tools=[{
        "type": "x_search",
        "allowed_x_handles": [
            "@concurrent1", "@concurrent2", "@concurrent3"
        ],
        "from_date": last_week,
        "to_date": today,
        "enable_image_understanding": True
    }]
)

print(response.output_text)

Points clés à retenir

• X Search coûte 5 $ pour 1 000 appels, ce qui en fait un outil de veille très abordable
• Vous pouvez filtrer par handles (max 10) ou dates (format ISO 8601), ou combiner les deux
• allowed_x_handles et excluded_x_handles sont mutuellement exclusifs
• L’analyse d’images et de vidéos dans les posts est une exclusivité de X Search (pas disponible sur Web Search)
• Utilisez l’API Responses (pas Chat Completions, qui est déprécié pour la recherche)