Passer au contenu principal
GET /v1/monitors/{id}/analytics (référence) renvoie chaque chiffre du rapport d’un moniteur à partir d’un seul ensemble de réponses : une fenêtre, un jeu de filtres, et la même fenêtre juste avant pour la comparaison. Construisez chaque panneau de votre propre rapport à partir de cet endpoint, et lisez quality avant les chiffres. La lecture d’un rapport ne coûte rien.

Paramètres de requête

La fenêtre est semi-ouverte et en UTC : since est inclus, until ne l’est pas. La fenêtre précédente a exactement la même durée, se termine à since et utilise les mêmes filtres : chaque comparaison se fait donc à conditions égales. Envoyez chaque paramètre une seule fois.

Exemple

Par exemple, un moniteur de marque qui pose deux prompts à ChatGPT une fois par jour avec samples: 5 (dix réponses par jour), filtré sur ChatGPT sur deux jours, renvoie :
Lecture : la marque a été citée dans 9 des 20 réponses de ChatGPT (45 %), soit 15 points de moins que les deux jours précédents. Northwind Audio a été cité dans davantage de réponses, et « are cheap earbuds worth it » est le prompt le plus faible, avec 4 réponses qui ont cité un concurrent et pas la marque. quality.lowSample vaut true : traitez donc la variation comme un signal à vérifier, pas comme une tendance.

Sections de la réponse

Objets de taux

stats, previous, chaque entrée de engineRates et de series, chaque prompt et chaque cellule portent les mêmes champs :

Cellules

Une cellule est un prompt sur un moteur. Outre l’objet de taux et previous, elle porte : Chaque id vaut null quand aucune réponse ne correspond. Ouvrez-en un avec GET /v1/monitors/{id}/answers/{taskId}.

Marques et part de voix

Chaque entrée de brands a name, mentions, sampleSize, mentionRate, shareOfVoice, previousMentionRate, previousShareOfVoice et configured (false pour une marque citée dans la fenêtre qui ne figure plus sur le moniteur).

Ce que signifient les chiffres

GET /v1/monitors/capabilities renvoie ces définitions sous metrics, pour qu’un client puisse les afficher à côté des chiffres.
  • mentionRate vaut 100 × mentioned / réponses notées, pour la fenêtre, chaque moteur, chaque jour et chaque cellule. Il est pondéré par les réponses, pas une moyenne entre moteurs : un moteur très actif ne peut pas être écrasé par un moteur peu actif.
  • citationRate a la même forme pour les réponses qui ont cité l’un de vos domaines. Sans domaine, il vaut toujours 0, car le suivi des citations est désactivé.
  • Le taux d’une marque se divise par son propre sampleSize. Pour votre marque, ce sont toutes les réponses notées. Pour un concurrent, seulement les réponses notées pendant qu’il figurait sur le moniteur : un concurrent ajouté aujourd’hui est mesuré à partir d’aujourd’hui. Le mentionRate d’un concurrent vaut null quand certaines réponses de la fenêtre ont été notées avant le stockage du contexte de notation, car on ignore à quoi elles ont été comparées.
  • shareOfVoice vaut 100 × mentions de cette marque / toutes les mentions des marques suivies dans la fenêtre : les parts d’une fenêtre totalisent donc 100 (quality.trackedBrandMentions est le dénominateur). Il compare les marques au sein des réponses que vous avez collectées pour ces prompts. Ce n’est ni une part de marché ni un classement de visibilité.
  • competitorOnly et opportunities comptent les réponses qui ont cité un concurrent alors que votre marque était absente : l’écart sur lequel vous pouvez agir.
  • null n’est pas 0. Un taux vaut null quand il n’y avait aucune réponse à diviser. 0 signifie qu’il y a eu des réponses et qu’aucune ne correspondait.
  • Une réponse sans texte compte comme non mentionnée. Une tâche terminée qui n’a renvoyé aucune réponse reste dans le dénominateur ; quality.noAnswerObservations les compte. Une tâche échouée est exclue de tous les taux et n’apparaît que dans health. Un moteur en panne réduit l’échantillon au lieu d’apparaître comme une absence.
  • position sur une réponse notée est l’offset de caractère de la première occurrence de votre marque : un indicateur de mise en avant, pas un rang. Il vaut null quand la marque est absente.

Quand les variations sont masquées

changes, le mentionRateChangePp de chaque cellule, et les previousMentionRate et previousShareOfVoice de chaque marque valent null, et quality.comparable vaut false, quand les deux fenêtres ne peuvent pas être comparées. quality.comparisonReason en donne la raison : Chaque réponse garde la définition avec laquelle elle a été notée, et quality.scoringVersions liste les définitions distinctes sur les deux fenêtres (legacy pour les réponses qui n’en ont pas). Modifier vos alias ou concurrents ne réécrit jamais les réponses passées. Seule exception : la lecture hebdomadaire des concurrents. Quand les concurrents qu’elle trouve changent, les réponses enregistrées du moniteur sont notées à nouveau avec la nouvelle liste.

Qualité

Santé

health contient completed, failed, pending et topError (le code d’erreur le plus fréquent parmi les tâches échouées) pour les tâches du moniteur en cours ou terminées au cours des dernières 24 heures. healthScope vaut toujours recent_visible_tasks. C’est un diagnostic des exécutions, indépendant de la fenêtre, et jamais une partie du dénominateur d’un taux.

Interroger pendant une exécution

Chaque appel renvoie le rapport complet pour la fenêtre et les filtres. Pendant une exécution, health.pending compte ses tâches encore en cours. Relisez le rapport quand il atteint 0.

Rapports de catégorie

Un moniteur de catégorie renvoie un corps différent depuis le même endpoint, avec les mêmes window, filters, quality, pauses et health :
  • stats et previous contiennent runs, named (réponses qui ont cité au moins une marque suivie) et namedRate. changes.namedRatePp est la variation en points.
  • category contient le classement :
Par exemple, une entrée de category.brands :
  • rank ordonne les marques selon le nombre de réponses qui les citent. Une marque qu’aucune réponse n’a citée a rank: null.
  • mentionRate se divise par le propre sampleSize de la marque : les réponses notées pendant qu’elle figurait dans la liste.
  • shareOfVoice vaut 100 × mentions de cette marque / toutes les mentions de marques dans la fenêtre : les parts totalisent donc 100.

Erreurs et limites

  • La fenêtre est de 90 jours au plus.
  • Des paramètres invalides renvoient 400 VALIDATION_ERROR avec un message qui nomme le problème : days avec since ou until, un seul de since et until, un horodatage sans fuseau horaire, un intervalle de plus de 90 jours, un until dans le futur, un moteur qui ne peut pas être suivi, un prompt de plus de 2 000 caractères, ou un paramètre répété.
  • Un rapport trop volumineux à agréger renvoie 400 VALIDATION_ERROR avec « This report is too large ». Réduisez la fenêtre, le moteur ou le prompt.
Voir Moniteurs pour les codes communs à tous les endpoints de moniteur.

Étapes suivantes

Sources et réponses

Les pages citées et les réponses derrière chaque chiffre.

Événements et alertes

Soyez prévenu quand les réponses changent.