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 avecsamples: 5 (dix réponses par
jour), filtré sur ChatGPT sur deux jours, renvoie :
Réponse complète
Réponse complète
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 etprevious, 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 debrands 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.
mentionRatevaut100 × 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.citationRatea 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. LementionRated’un concurrent vautnullquand 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. shareOfVoicevaut100 × mentions de cette marque / toutes les mentions des marques suiviesdans la fenêtre : les parts d’une fenêtre totalisent donc 100 (quality.trackedBrandMentionsest 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é.competitorOnlyetopportunitiescomptent les réponses qui ont cité un concurrent alors que votre marque était absente : l’écart sur lequel vous pouvez agir.nulln’est pas 0. Un taux vautnullquand 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.noAnswerObservationsles compte. Une tâche échouée est exclue de tous les taux et n’apparaît que danshealth. Un moteur en panne réduit l’échantillon au lieu d’apparaître comme une absence. positionsur 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 vautnullquand 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êmeswindow, filters, quality, pauses et health :
statsetpreviouscontiennentruns,named(réponses qui ont cité au moins une marque suivie) etnamedRate.changes.namedRatePpest la variation en points.categorycontient le classement :
Par exemple, une entrée de
category.brands :
rankordonne les marques selon le nombre de réponses qui les citent. Une marque qu’aucune réponse n’a citée arank: null.mentionRatese divise par le propresampleSizede la marque : les réponses notées pendant qu’elle figurait dans la liste.shareOfVoicevaut100 × mentions de cette marque / toutes les mentions de marquesdans 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_ERRORavec un message qui nomme le problème :daysavecsinceouuntil, un seul desinceetuntil, un horodatage sans fuseau horaire, un intervalle de plus de 90 jours, ununtildans 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_ERRORavec « This report is too large ». Réduisez la fenêtre, le moteur ou le prompt.
É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.