Passer au contenu principal
Vous créez un moniteur une fois. Chaque exécution est un ensemble de tâches asynchrones ordinaires, facturées au prix de chaque moteur. Cette page couvre la création, l’exécution et la gestion des moniteurs. La lecture des chiffres se trouve dans Rapports et métriques, les réponses qui les sous-tendent dans Sources et réponses, et les webhooks et alertes e-mail dans Événements et alertes. Pour la vue tableau de bord des mêmes données, consultez la page produit.

Moniteurs de marque et de catégorie

Un moniteur a un mode, 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. position est l’offset de caractère de la première occurrence, ou null quand la marque est absente.
  • Citée : la réponse cite une page de l’un de vos domains ou d’un de leurs sous-domaines.
  • Concurrents détectés : lesquels des concurrents du moniteur apparaissent dans la même réponse.
Ces notes ne portent aucun sentiment ni aucune estimation de part de marché. Le rang d’un moniteur de catégorie est une place parmi les marques que citent les réponses, rien de plus. Pour le sentiment et les recommandations par réponse, activez 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

Lisez d’abord quality, puis stats, brands et opportunities. Chaque champ est expliqué dans Rapports et métriques.
Pour obtenir des réponses avant la prochaine exécution planifiée, appelez 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 portent source: "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. competitorsReadAt indique la date de la dernière lecture.
  • Lors d’une mise à jour, competitors remplace votre propre liste et conserve les concurrents trouvés. Les entrées avec source: "auto" dans la requête sont ignorées : vous pouvez donc renvoyer ce que GET a 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’intervalHours du moniteur, jusqu’à 168. Le moteur participe toutes les k exécutions, en comptant depuis la première, à laquelle tous les moteurs participent.
Une entrée ne peut nommer qu’un des moteurs du moniteur et n’accepte que ces deux clés. Lors d’une mise à jour, 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 :
  • location pose chaque prompt depuis un point, en degrés décimaux.
  • grid pose chaque prompt depuis chaque point d’une grille carrée autour de center. size est 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é.
Seuls 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 dans display.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 dans answer.analysis de GET /v1/monitors/{id}/answers/{taskId}.
Un moniteur avec location ou grid ajoute 1 crédit à chaque tâche. La lecture des rapports, sources, réponses et résultats ne coûte rien.
Le calendrier se répète jusqu’à ce que vous mettiez en pause ou supprimiez le moniteur. Le chiffre mensuel ci-dessus est ce à quoi vous vous engagez en le créant.
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_ERROR en 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. nextRunAt est le moment où la prochaine exécution est due. Reprendre un moniteur en pause, ou changer intervalHours, 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.
Par exemple :
Les suggestions qui contiennent le nom de la marque ou un alias sont retirées. Relisez la liste avant de créer le moniteur. Vous pouvez demander une suggestion toutes les 20 secondes et 30 par heure ; au-delà, l’appel renvoie 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.
La réponse contient la tâche en file d’attente dans 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 avec promptTopics :
Un moniteur de catégorie n’a pas de marque propre : 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: false met le moniteur en pause ; enabled: true le reprend, avec la prochaine exécution un intervalle plus tard. Les pauses apparaissent dans les rapports sous pauses.
  • Modifier alertBelowPct ré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’adresse https://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 :
  1. GET /v1/monitors/capabilities : les moteurs, les prix et les limites avant de dépenser quoi que ce soit.
  2. GET /v1/monitors : réutilisez un moniteur pour le sujet et le marché, ou créez-en un, éventuellement à partir de POST /v1/monitors/suggest.
  3. POST /v1/monitors/{id}/run uniquement si vous avez besoin de réponses avant la prochaine exécution planifiée.
  4. GET /v1/monitors/{id}/analytics?days=30 : lisez quality avant les chiffres, et attendez que health.pending atteigne 0.
  5. GET /v1/monitors/{id}/sources?days=30&groupBy=page : suivez nextCursor jusqu’au bout.
  6. GET /v1/monitors/{id}/answers/{taskId} : ouvrez la réponse derrière la première entrée de opportunities avant d’agir.
  7. GET /v1/monitors/{id}/results?since=...&until=...&format=csv : exportez la même fenêtre en suivant x-next-cursor jusqu’à 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.