list_competitors

list_competitors retourne les concurrents trackés sur un projet, avec totaux de mentions, position moyenne, LLMs où ils sont mentionnés et nombre de prompts sur lesquels ils apparaissent. Trois statuts sont supportés : CONFIRMED, SUGGESTED (auto-détecté, en attente de modération), REJECTED.

Chaque ligne porte aussi le verdict posé par l'IA ou par une personne. Sur un projet e-commerce (une marque qui vend des produits en ligne, voir update_project_settings), les entités citées dans les réponses sont triées en marques concurrentes, revendeurs (là où l'acheteur est envoyé : Amazon, pharmacies, marketplaces) et produits (noms de produits). Revendeurs et produits ne sont jamais CONFIRMED : ils restent hors de la liste par défaut.

Quand l'utiliser

Sortez ce tool quand l'utilisateur demande "contre qui je me bats dans les réponses IA ?", "qui prend de la visibilité sur mes prompts ?", "liste les nouveaux concurrents à modérer". Le filtre par défaut filters.status: ["CONFIRMED"] retourne les concurrents validés ; passez à ["SUGGESTED"] pour traiter la file d'auto-détection, ou filtrez par verdict pour lister les revendeurs ou les produits d'un projet e-commerce. Combinez avec bulk_update_competitor_status pour agir sur le résultat.

Paramètres

Réponse

Chaque ligne est un concurrent avec ses aliases, son status, son verdict, sa source et un bloc stats. verdict vaut COMPETITOR, NOT_COMPETITOR, UNSURE, RETAILER, PRODUCT, ou null quand l'entité n'a pas encore été jugée. Le summary.byStatus au niveau racine permet à l'agent de voir la file de modération sans second appel.

{
  "data": [
    {
      "id": "clxcomp001",
      "canonicalName": "Otterly",
      "aliases": ["Otterly.ai", "OtterlyAI"],
      "status": "CONFIRMED",
      "verdict": "COMPETITOR",
      "source": "auto-detected",
      "createdAt": "2026-02-15T00:00:00.000Z",
      "stats": {
        "totalMentions": 89,
        "averagePosition": 2.3,
        "llmsWhereMentioned": ["CHATGPT", "PERPLEXITY"],
        "promptCoverage": 12
      }
    }
  ],
  "pageInfo": { "hasMore": false, "nextCursor": null, "totalCount": 7 },
  "summary": {
    "totalCompetitors": 7,
    "byStatus": { "CONFIRMED": 7, "SUGGESTED": 12, "REJECTED": 3 }
  }
}

Conseils et patterns

• Triez par mentions_desc pour de la veille concurrentielle ; triez par created_desc pour faire remonter les nouveaux entrants dans la file d'auto-détection.
• averagePosition est calculée sur les runs où le concurrent était mentionné. Un faible totalMentions la rend bruitée.
• promptCoverage est le nombre de prompts distincts où le concurrent apparaît. Croisez avec list_prompts pour voir lesquels se chevauchent avec votre couverture.
• Listez les revendeurs d'un projet e-commerce avec filters.verdict: ["RETAILER"] (et les produits avec ["PRODUCT"]). Le filtre de statut couvre alors tous les statuts par défaut : rien n'est masqué.
• Un concurrent qui est en fait un revendeur ou un produit se déplace avec bulk_update_competitor_status et son champ kind.
• Tirez régulièrement filters.status: ["SUGGESTED"] et passez les IDs à bulk_update_competitor_status pour garder le dataset propre.

Tools liés

• list_competitor_sources : domaines où un concurrent donné est cité.
• bulk_update_competitor_status : confirmer, rejeter ou reclasser des concurrents en masse.
• update_project_settings : activer le tri e-commerce d'un projet.
• list_prompts : voir votre propre visibilité sur les mêmes prompts.