Moniteurs de marque et de catégorie
Un moniteur a unmode, défini à sa création et fixe pendant toute sa vie, car il détermine le sens de chaque
réponse stockée.
Chaque réponse est notée une fois, à son arrivée :
- Mentionnée : l’un de vos alias apparaît dans le texte de la réponse.
positionest l’offset de caractère de la première occurrence, ounullquand la marque est absente. - Citée : la réponse cite une page de l’un de vos
domainsou d’un de leurs sous-domaines. - Concurrents détectés : lesquels des concurrents du moniteur apparaissent dans la même réponse.
analysis.
Démarrage rapide
1
Créer le moniteur
La première exécution démarre dès la création du moniteur.La réponse est un
201 avec le moniteur enregistré. Conservez data.monitor.id.2
Attendre les réponses
Les tâches sont admises au rythme que permet la concurrence de votre offre : une exécution arrive donc en quelques secondes à quelques minutes.
Le champ
health.pending du rapport compte les tâches encore en cours. Lisez le rapport quand il atteint 0.3
Lire le rapport
quality, puis stats, brands et opportunities. Chaque champ est expliqué dans
Rapports et métriques.POST /v1/monitors/{id}/run.
Créer un moniteur
POST /v1/monitors (référence) valide la définition,
la vérifie par rapport aux limites de votre compte, l’enregistre et lance la première exécution. L’appel renvoie 201
avant la fin de cette exécution. Si la première exécution ne peut pas démarrer (par exemple, solde insuffisant), le
moniteur est tout de même créé et le planificateur retente l’exécution chaque minute.
Par exemple, la requête du démarrage rapide renvoie :
Champs de la requête
Chaque champ de liste accepte un tableau JSON ou une chaîne unique séparée par des retours à la ligne. Les entrées sont nettoyées, les entrées vides supprimées et les doublons retirés.Moteurs
Un moniteur peut planifier les moteurs de réponse à base de prompt :CHATGPT, GEMINI, PERPLEXITY, GOOGLE
(Google AI Overviews), AIMODE (Google AI Mode), NAVER_AI_BRIEF, NAVER_AI_TAB, et NAVER, un
nom obsolète conservé pour les moniteurs existants. Les alias GOOGLE_AIO, GOOGLE_AIMODE et
NAVER_AI_MODE sont acceptés et stockés comme GOOGLE, AIMODE et NAVER_AI_TAB. Les noms de moteur sont
sensibles à la casse. Les types de tâche de recherche, de données web et d’analyse, comme GOOGLE_SERP ou CITATION_ANALYSIS,
ne peuvent pas être planifiés. Les prix et le détail de chaque moteur se trouvent dans le catalogue des moteurs.
Une clé d’API restreinte à certains moteurs ne peut créer, mettre à jour ou exécuter que les moniteurs qui utilisent ces moteurs ;
tout le reste renvoie 403 KEY_SCOPE_DENIED.
Concurrents
Vous n’avez pas à lister de concurrents. Après la première exécution, une lecture hebdomadaire des réponses récentes du moniteur ajoute les marques qui vendent la même chose que vous et apparaissent dans au moins deux réponses : jusqu’à 15 sur un moniteur de marque, 25 sur un moniteur de catégorie.- Les concurrents trouvés portent
source: "auto"; ceux que vous listez portentsource: "user". La lecture ne modifie ni ne supprime jamais les vôtres. Une marque trouvée que les deux lectures suivantes ne retrouvent pas est retirée. - Quand la liste trouvée change, les réponses enregistrées du moniteur sont notées à nouveau avec elle, afin que chaque marque
d’un rapport soit mesurée sur les mêmes réponses.
competitorsReadAtindique la date de la dernière lecture. - Lors d’une mise à jour,
competitorsremplace votre propre liste et conserve les concurrents trouvés. Les entrées avecsource: "auto"dans la requête sont ignorées : vous pouvez donc renvoyer ce queGETa retourné.
Correspondance des noms
- La correspondance ignore la casse et la largeur des caractères (NFKC).
- Les noms en alphabet latin ne correspondent qu’à des mots entiers : « replicates » n’est pas une mention d’une marque appelée Replicate. Une lettre coréenne, japonaise, chinoise ou thaïe collée au nom compte comme une limite de mot : « agoda를 » et « ahamoが » mentionnent agoda et ahamo. Les noms coréens, japonais, chinois et thaïs correspondent n’importe où dans le texte.
- Un nom d’un seul caractère ne correspond jamais. Donnez à une telle marque un alias plus long.
- Quand deux noms se chevauchent, celui qui commence en premier, puis le plus long, l’emporte. « Acme » à l’intérieur d’un concurrent nommé « Acme Pro » compte pour le concurrent.
- Les cibles de lien, les URL nues et les puces de citation sont retirées avant la correspondance ; le texte visible d’un lien est
conservé. Une citation compte pour
cited, pas comme une mention.
Rédiger des prompts qui mesurent quelque chose
- Un moniteur par sujet et par marché. « meilleur CRM » et « comment fixer le prix d’un CRM » sont des intentions différentes ; en faire la moyenne masque les deux.
- Formulez les prompts comme un acheteur et n’y mettez jamais votre propre marque. Un prompt qui contient la marque est toujours une mention : il affiche 100 % et ne mesure rien. Les noms de concurrents dans les prompts conviennent.
Échantillons et cadence par moteur
Les réponses d’IA changent d’une session à l’autre, si bien qu’une part sur plusieurs réponses est plus stable qu’une réponse seule.engineSettings définit, par moteur, combien de réponses collecter par prompt et à quelle fréquence le moteur s’exécute :
samples: 1 à 10 réponses par prompt et par point à chaque exécution (1 par défaut). Chacune est une tâche distincte dans sa propre session, notée et facturée comme toute autre.intervalHours: un multiple de l’intervalHoursdu moniteur, jusqu’à 168. Le moteur participe toutes les k exécutions, en comptant depuis la première, à laquelle tous les moteurs participent.
engineSettings remplace la valeur stockée ; une mise à jour qui retire un moteur retire son entrée, et une mise à jour qui
change l’intervalHours du moniteur revérifie les intervalles des moteurs avec la nouvelle valeur.
Localisation et grilles
Par défaut, chaque tâche interroge pour le pays dans son ensemble. Pour mesurer des réponses locales :locationpose chaque prompt depuis un point, en degrés décimaux.gridpose chaque prompt depuis chaque point d’une grille carrée autour decenter.sizeest le nombre de points par côté : 3, 5, 7 ou 9 (9 à 81 points).radiusMeters, de 100 à 50 000, est la distance entre le centre et le milieu d’un côté.
CHATGPT, GEMINI, GOOGLE et AIMODE répondent pour une localisation. Un moniteur avec une localisation ou une grille
et tout autre moteur est refusé avec 400 VALIDATION_ERROR. Lors d’une mise à jour, définir location ou
grid efface l’autre, et null l’efface. Lisez les réponses par point avec
GET /v1/monitors/{id}/grid.
Pages de réponse
Une réponse dont la tâche a enregistré une page porte son adresse dansdisplay.html, et le panneau la livre en fichier avec les polices intégrées. La page est l’écran réel du moteur, pas un nouveau rendu du markdown.
Les exécutions d’un moniteur ne demandent pas de page : leurs réponses n’en portent pas. L’adresse est relue depuis la tâche dès qu’une en a enregistré une, donc une page gardée reste ouvrable depuis sa réponse.
Coût et calendrier
Une exécution crée, pour chaque moteur qui y participe, une tâche par prompt, par point et par échantillon :points vaut 1 sans grille. Par exemple, 12 prompts sur CHATGPT (1 crédit) et GOOGLE (1,25 crédit)
font 24 tâches et 27 crédits par exécution, soit environ 810 crédits par mois à un intervalle quotidien. Avec
"CHATGPT": { "samples": 5 }, le même moniteur fait 72 tâches et 75 crédits par exécution. Lisez les prix en vigueur
depuis GET /v1/monitors/capabilities au lieu de les coder en dur ; la façon dont les crédits sont réservés
et prélevés est décrite dans Crédits et limites.
Deux frais s’ajoutent aux tâches :
- Lecture des concurrents : 80 crédits par période de 30 jours et par moniteur, répartis entre ses exécutions selon la cadence (environ 2,67 crédits par exécution pour un moniteur quotidien, 18,67 pour un hebdomadaire). Ils sont prélevés une fois toutes les tâches d’une exécution soumises : une exécution arrêtée par votre solde ne paie rien pour cela.
- Analyse de la réponse : avec
analysis: true, 1 crédit par tâche, facturé seulement pour les réponses analysées. Les notes (mentioned,cited,position) ne changent pas ; le résultat de chaque réponse se trouve dansanswer.analysisdeGET /v1/monitors/{id}/answers/{taskId}.
location ou grid ajoute 1 crédit à chaque tâche.
La lecture des rapports, sources, réponses et résultats ne coûte rien.
Comportement du calendrier :
- Une exécution n’est pas une rafale. Les tâches sont soumises au rythme que permettent la concurrence de votre offre et les files des moteurs. Chaque minute, le planificateur reprend là où il s’est arrêté, une tâche par moteur à tour de rôle, et les moniteurs de comptes différents passent chacun leur tour. Un compte parent et ses sous-comptes partagent les mêmes tours.
- Une exécution doit tenir dans son intervalle. Si les tâches d’un moteur ne peuvent pas être admises avant que ce moteur ne s’exécute
à nouveau, la création et la mise à jour renvoient
400 VALIDATION_ERRORen indiquant le plus court intervalle qui convient. Une exécution encore en cours de soumission quand un intervalle complet s’est écoulé est close, et ses tâches restantes ne sont pas envoyées. - Les exécutions manquées ne sont pas rejouées.
nextRunAtest le moment où la prochaine exécution est due. Reprendre un moniteur en pause, ou changerintervalHours, planifie la prochaine exécution un intervalle après ce moment.
Capacités
GET /v1/monitors/capabilities (référence) renvoie, pour votre
compte : chaque moteur planifiable avec creditsPerTask, analysisCreditsPerTask et placeCreditsPerTask, vos limits, les
modes, les définitions des métriques (metrics), les formules du calendrier et les types d’événements de changement. Il n’a pas
d’effet de bord et ne coûte rien ; appelez-le avant de créer des moniteurs par programme.
Choisir les prompts
Suggérer des prompts à partir des informations de marque
POST /v1/monitors/suggest (référence) renvoie jusqu’à 12
prompts candidats, rédigés comme les poserait un acheteur dans country. Il n’enregistre rien et ne consomme aucun crédit.
429 RATE_LIMITED. Quand le modèle refuse la marque, l’appel renvoie 400 SUGGEST_FAILED ; quand le
service de suggestion échoue, 502 SUGGEST_FAILED ; et quand il n’est pas configuré, 503 SUGGEST_FAILED.
Rechercher des prompts à partir de la demande de recherche
POST /v1/monitors/research (référence) prend le corps de requête
de Prompt Research, coûte les mêmes 14 crédits et renvoie le même
résultat, sous forme de tâche appartenant à votre compte.
data.task, avec data.credits et data.replayed. Lisez le
résultat avec GET /v1/async/task/{id} à l’aide de data.task.id (voir Tâches asynchrones).
Créez ensuite le moniteur avec prompts[].prompt comme prompts, dans leur ordre ; sur un moniteur de catégorie, quand
la recherche a plus d’un core, le core de chaque prompt comme son entrée dans promptTopics, et brands[].brand
comme competitors. Rien n’est enregistré tant que vous n’avez pas créé le moniteur.
Une exécution peut mettre en file au plus la limite tasksPerRun de votre compte, comptée sur chaque moteur comme
prompts × points de localisation × samples : réglez donc limit pour le moniteur que vous allez créer. Voir
De la recherche au moniteur.
Moniteurs de catégorie
Un moniteur de catégorie classe les marques que citent les moteurs pour un marché. Regroupez ses prompts par sous-domaine avecpromptTopics :
aliases, domains et alertBelowPct doivent être vides, sinon la
requête renvoie 400 VALIDATION_ERROR, et il n’a pas d’alerte. Ses stats.mentioned et stats.cited dans
GET /v1/monitors valent toujours 0 ; la liste ajoute leader, la marque la plus citée sur les 30 derniers jours. Son
rapport est décrit dans Rapports de catégorie. Le calendrier, le coût, les sources,
les réponses, les résultats et les événements de changement fonctionnent comme sur un moniteur de marque, sauf qu’un moniteur de catégorie n’envoie que
des événements monitor.source.first_cited.
Lors d’une mise à jour, une modification de prompts retire les entrées promptTopics des prompts supprimés. Les réponses que ces
prompts ont collectées restent dans le classement.
Gérer les moniteurs
L’ancien résumé de période de
GET /v1/monitors/{id} est conservé pour compatibilité. Pour les chiffres, utilisez
/analytics : l’ancien résumé mêle aux chiffres de la fenêtre une matrice sur tout l’historique de la dernière
réponse par prompt et par moteur, tronque les sources à 12 domaines et 20 pages, et son
shareOfVoice compte chaque marque par rapport à toutes les réponses, si bien que les parts peuvent dépasser 100 au total.
Un moniteur appartenant à un autre compte renvoie 404 NOT_FOUND, pas 403.
Mettre à jour un moniteur
PATCH accepte n’importe quel sous-ensemble des champs de création et valide le résultat dans son ensemble, avec les mêmes
limites. Les champs omis conservent leur valeur.
enabled: falsemet le moniteur en pause ;enabled: truele reprend, avec la prochaine exécution un intervalle plus tard. Les pauses apparaissent dans les rapports souspauses.- Modifier
alertBelowPctréarme l’alerte. - Modifier les alias, domaines ou concurrents affecte les réponses notées à partir de ce moment. Les réponses enregistrées gardent les définitions avec lesquelles elles ont été notées : les rapports masquent donc les comparaisons de part et d’autre du changement (voir Rapports et métriques).
Exécuter un moniteur maintenant
POST /v1/monitors/{id}/run rend la prochaine exécution due immédiatement ; le planificateur la démarre dans la
minute environ et l’appel renvoie data.queued: true. L’exécution est facturée comme une exécution planifiée. Relancer l’appel tant que
cette exécution est encore due ne crée pas de seconde exécution.
Avant la mise en file, l’appel vérifie que votre solde couvre l’exécution, y compris la lecture des concurrents et les
crédits d’analyse. Sinon, il renvoie 402 INSUFFICIENT_CREDITS avec details.needed et
details.available. Un sous-compte au-delà de sa limite mensuelle de crédits reçoit 429 SUB_ACCOUNT_CREDIT_LIMIT. Un
moniteur en pause renvoie 404 NOT_FOUND : reprenez-le d’abord.
Partager un rapport
Vous pouvez publier le rapport d’un moniteur à l’adressehttps://querying.ai/<slug>. Un rapport partagé affiche les
analytics, les sources, les citations, les résultats et les réponses ; il n’affiche jamais les réglages, les alertes, les commandes d’exécution ni
la santé des tâches de votre compte.
GET /v1/monitors/{id}/share (référence) renvoie l’état actuel,
access, slug, locale et url, plus un suggestedSlug quand aucun n’est défini.
PUT /v1/monitors/{id}/share (référence) le modifie :
Passer
access à PRIVATE met le rapport hors ligne et conserve le slug : réactiver le partage
réutilise donc la même adresse.
Utiliser les moniteurs depuis un agent
Le serveur MCP expose les moniteurs sous forme d’outils :get_monitor_capabilities, list_monitors,
get_monitor, create_monitor, update_monitor, delete_monitor, run_monitor,
get_monitor_analytics, get_monitor_sources, get_monitor_results, get_monitor_answer,
suggest_monitor_prompts, get_monitor_alerts et test_monitor_alert. Chacun effectue un appel d’API avec votre
clé.
Une séquence pratique pour un agent ou un script :
GET /v1/monitors/capabilities: les moteurs, les prix et les limites avant de dépenser quoi que ce soit.GET /v1/monitors: réutilisez un moniteur pour le sujet et le marché, ou créez-en un, éventuellement à partir dePOST /v1/monitors/suggest.POST /v1/monitors/{id}/rununiquement si vous avez besoin de réponses avant la prochaine exécution planifiée.GET /v1/monitors/{id}/analytics?days=30: lisezqualityavant les chiffres, et attendez quehealth.pendingatteigne0.GET /v1/monitors/{id}/sources?days=30&groupBy=page: suiveznextCursorjusqu’au bout.GET /v1/monitors/{id}/answers/{taskId}: ouvrez la réponse derrière la première entrée deopportunitiesavant d’agir.GET /v1/monitors/{id}/results?since=...&until=...&format=csv: exportez la même fenêtre en suivantx-next-cursorjusqu’à ce qu’il soit vide.
Limites
Un compte sous contrat est un compte avec une limite de concurrence négociée. Les limites suivantes s’appliquent à tous les comptes :
Les limites de rapport, de taille de page et de conservation figurent sur les pages qui les utilisent :
Rapports et métriques, Sources et réponses et
Événements et alertes.
Erreurs
L’enveloppe d’erreur est la même que partout ailleurs (voir Erreurs). Codes propres aux moniteurs :Étapes suivantes
Rapports et métriques
Le contrat
/analytics et le sens de chaque chiffre.Sources et réponses
Les pages citées, les réponses derrière chaque note, et les exports.
Événements et alertes
Des webhooks quand les réponses changent, et des alertes e-mail sur votre taux de mention.
Prompt Research
Trouvez les prompts qui méritent d’être suivis à partir de la demande de recherche.