> ## Documentation Index
> Fetch the complete documentation index at: https://docs.querying.ai/llms.txt
> Use this file to discover all available pages before exploring further.

# API de suivi GEO : mentions et citations de marque

> Planifiez des jeux de prompts, lisez un contrat de rapport unique au dénominateur explicite et exportez les réponses derrière chaque chiffre.

Les moniteurs rejouent un jeu de prompts enregistré selon un calendrier et notent les réponses IA obtenues pour votre
marque et ses concurrents. Cette page est le contrat de l'API : comment configurer un moniteur, ce que signifie chaque
chiffre, comment lire les sources qui le sous-tendent et comment exporter les réponses sous-jacentes. Pour la vue
tableau de bord des mêmes données, commencez par le [guide produit](https://querying.ai/fr/monitors).

Toutes les clés, ids, marques et prompts de cette page sont des exemples. Rien ici n'est un identifiant ni un moniteur réel.

## Qu'est-ce qu'un moniteur

Un moniteur est un **jeu de prompts nommé sur un marché** : une liste de prompts, les moteurs auxquels les envoyer, les
alias qui signifient « votre marque », éventuellement vos domaines et quelques concurrents, un pays et un intervalle.
Chaque exécution planifiée soumet prompts × moteurs tâches asynchrones ordinaires, et chaque réponse terminée est notée
une fois puis conservée.

La notation est volontairement étroite, et les données ne peuvent pas répondre au-delà de ce qu'elles stockent :

* Elle enregistre si un alias de marque apparaît dans le texte de la réponse et à quel offset de caractère ; si la
  réponse a cité l'un de vos domaines enregistrés ; et lesquels de vos concurrents configurés sont apparus dans la même réponse.
* Elle ne produit **pas** de score de sentiment ni d'estimation de part de marché. Un rang est une place parmi
  les marques que citent les réponses, comme dans le classement d'un moniteur de catégorie (voir plus bas).

### Les concurrents sont trouvés pour vous

Vous n'avez pas à lister de concurrents. Dès que la première exécution d'un moniteur est terminée, nous lisons ses réponses
récentes avec un modèle de langage et gardons les marques qui vendent la même chose que vous et sont citées dans au moins
deux réponses, 15 au maximum. La lecture se répète tous les 30 jours : les nouveaux rivaux apparaissent et ceux qui ne sont
plus cités disparaissent.

* Les concurrents trouvés portent `source: "auto"`. Ceux que vous ajoutez portent `source: "user"`, et la lecture ne les
  modifie ni ne les supprime jamais.
* Quand la liste trouvée change, les réponses enregistrées du moniteur sont recomptées avec elle, afin que chaque marque d'un
  rapport soit mesurée sur les mêmes réponses. `competitorsReadAt` sur le moniteur indique la date de la dernière lecture.
* Les noms en alphabet latin correspondent à des mots entiers : « replicates » ne compte pas comme une mention de la marque Replicate.

### Séparez les moniteurs de façon réfléchie

Des moniteurs distincts représentent des sujets ou marchés distincts, et ce sont des rapports distincts : chacun a sa
propre fenêtre, sa propre définition de notation et son propre calendrier. Deux habitudes sont payantes :

* Un moniteur par sujet et par marché, pour que la cohorte d'un rapport reste comparable. Mélanger « meilleur CRM » et
  « comment fixer le prix d'un CRM » dans un même jeu fait la moyenne de deux intentions différentes en un seul chiffre.
* Formulez les prompts comme un acheteur et n'y mettez jamais votre propre marque. Un prompt contenant la marque est
  toujours une mention : il affiche 100 % pour toujours et ne mesure rien. Les noms de concurrents conviennent et font
  souvent les prompts les plus utiles.

## Moniteurs de catégorie : classez les marques d'un marché

Un moniteur de marque suit une marque. Un **moniteur de catégorie** suit un marché : vous nommez la catégorie, vous
regroupez ses questions par sous-domaine, et le rapport classe les marques que citent les moteurs en y répondant.
Définissez `"mode": "CATEGORY"` à la création du moniteur. `mode` vaut `BRAND` par défaut et reste fixe pendant toute la
vie du moniteur, car il détermine le sens de chaque ligne stockée.

```bash theme={null}
curl -X POST "$BASE/v1/monitors" \
  -H "Authorization: Bearer $QUERYING_API_KEY" -H "Content-Type: application/json" \
  -d '{
    "name": "Sunscreen market",
    "mode": "CATEGORY",
    "category": "Sunscreen",
    "engines": ["CHATGPT", "GEMINI"],
    "prompts": ["best sunscreen for sensitive skin", "best sunscreen for kids"],
    "promptTopics": {
      "best sunscreen for sensitive skin": "Sensitive skin",
      "best sunscreen for kids": "Kids"
    },
    "competitors": [{ "name": "Supergoop" }, { "name": "La Roche-Posay", "aliases": ["LRP"] }],
    "country": "US",
    "intervalHours": 24
  }'
```

| Champ | Sur un moniteur de catégorie |
| - | - |
| `category` | Obligatoire, de 1 à 80 caractères : le marché tel qu'un acheteur le nomme. |
| `promptTopics` | Associe un prompt (son texte exact) à son sous-domaine. Jusqu'à 30 sous-domaines de 60 caractères au maximum. Un prompt sans entrée couvre toute la catégorie. |
| `competitors` | Les marques à classer : jusqu'à 25 que vous listez. Une fois la première exécution terminée, la lecture mensuelle en ajoute jusqu'à 25 autres que citent les réponses. |
| `aliases` · `domains` · `alertBelowPct` | Laissez-les vides. Un moniteur de catégorie n'a ni marque propre, ni domaine possédé, ni alerte : une valeur renvoie `400 VALIDATION_ERROR`. |

Le calendrier, le coût, la fenêtre, les filtres, `quality`, les sources, les citations, les résultats et les réponses
fonctionnent comme sur un moniteur de marque. Un moniteur de catégorie n'a pas d'alerte, donc
`POST /v1/monitors/{id}/alerts/test` renvoie `400`.

### Ce que classe le rapport

`GET /v1/monitors/{id}/analytics` renvoie la vue de catégorie. `stats` et `previous` contiennent `runs`, `named`
(réponses qui citent au moins une marque suivie) et `namedRate` ; `changes.namedRatePp` est la variation en points, et
l'objet `category` contient le classement :

| Champ | Ce qu'il contient |
| - | - |
| `category.brands` | Chaque marque suivie que les réponses ont citée, celles citées dans le plus de réponses d'abord : `rank`, `mentions`, `sampleSize`, `mentionRate`, `shareOfVoice` et la variation par rapport à l'intervalle précédent. |
| `category.topics` | Une ligne par sous-domaine (`topic: null` est toute la catégorie) avec ses `runs`, son `namedRate` et les trois marques les plus citées. |
| `category.engines` | Une ligne par moteur avec les trois marques qu'il cite le plus. |
| `category.series` | Par jour UTC, les taux des cinq marques en tête. |
| `category.prompts` | Une ligne par prompt avec ses marques en tête et ses cellules par moteur ; chaque cellule porte un `evidenceTaskId` pour ouvrir la réponse derrière. |

* **`rank`** ordonne les marques selon le nombre de réponses qui les citent : c'est une place parmi les marques que
  citent ces réponses. Une marque qu'aucune réponse n'a citée a `rank: null`.
* **Le `mentionRate` d'une marque** se divise par son propre `sampleSize`, les réponses notées pendant que la marque
  figurait dans la liste. Une marque ajoutée aujourd'hui est mesurée à partir d'aujourd'hui.
* **`shareOfVoice`** vaut `100 × mentions de cette marque / toutes les mentions de marques suivies` dans la fenêtre :
  les parts d'une même fenêtre totalisent donc 100.
* `GET /v1/monitors` ajoute `leader` (la marque la plus citée, avec son taux) à chaque moniteur de catégorie. Ses
  compteurs `mentioned` et `cited` valent toujours `0`.
* `GET /v1/monitors/{id}/answers/{taskId}` renvoie `mode`, un `aliases` vide et les marques suivies comme `competitors`.

### Rechercher des prompts à partir de la demande de recherche

`POST /v1/monitors/research` prend le corps de requête de [Prompt Research](/fr/research/prompt-research), coûte les mêmes
12 crédits et renvoie le même résultat, soumis au nom de votre compte. Lisez la tâche en file d'attente avec
`GET /v1/async/task/{id}` ; l'id se trouve dans `data.task.id` de la réponse.

```bash theme={null}
curl -X POST "$BASE/v1/monitors/research" \
  -H "Authorization: Bearer $QUERYING_API_KEY" -H "Content-Type: application/json" \
  -d '{ "seed": "sunscreen", "country": "US", "monitorSize": 10, "monitorEngines": ["CHATGPT", "GEMINI"] }'
```

Utilisez `monitorSet.prompts` comme `prompts`, le `topic` de chaque prompt comme son sous-domaine dans `promptTopics`, et
`brands[].brand` comme `competitors`. Le bouton **Lancer la recherche** du tableau de bord fait la même chose et remplit
le formulaire ; rien n'est enregistré tant que vous n'avez pas créé le moniteur.

## Coût et calendrier

Une exécution met en file une tâche par prompt et par moteur, au prix en crédits publié de chaque moteur. Le calendrier
se répète jusqu'à ce que vous mettiez en pause ou supprimiez le moniteur : c'est donc un coût récurrent que vous
choisissez à la création :

```text theme={null}
credits per run  = prompts × sum(credits for each engine)
credits / month  ≈ credits per run × (24 × 30) / intervalHours
```

Par exemple, 12 prompts sur ChatGPT (2 crédits) et Gemini (1 crédit) font 24 tâches et 36 crédits par exécution, soit
environ 1 080 crédits par mois à un intervalle quotidien. Lisez les prix en vigueur depuis l'endpoint capabilities au
lieu de les coder en dur.

Deux propriétés du calendrier sont bonnes à connaître avant de s'y fier :

* Une exécution n'est **pas** une rafale. Les tâches sont admises au rythme que permettent la concurrence de l'offre et
  la file : une exécution qui dépasse la limite d'une offre gratuite arrive sur plusieurs minutes au lieu d'être
  abandonnée. Surveillez `health.pending` dans un rapport pour voir une exécution en cours.
* La fenêtre suivante est un horaire, pas une garantie. `nextRunAt` est le moment où l'exécution est due ; un moniteur
  en pause pendant une semaine reprend un intervalle après sa réactivation au lieu de lancer les exécutions manquées.

La recherche de vos concurrents ajoute 100 crédits par mois et par moniteur, répartis entre ses exécutions selon
l'intervalle : environ 3 crédits par exécution pour un moniteur quotidien, environ 23 pour un hebdomadaire. Ils sont
prélevés une fois toutes les tâches d'une exécution admises : une exécution arrêtée par votre solde ne paie rien pour cela.

## Endpoints

| Méthode et chemin | Ce qu'il fournit |
| - | - |
| `GET /v1/monitors/capabilities` | Les moteurs avec leurs prix en crédits, les limites, les définitions des métriques et l'économie du calendrier. Une lecture peu coûteuse sans effet de bord. |
| `GET /v1/monitors` | Vos moniteurs, avec un cumul sur 30 jours pour chacun. |
| `POST /v1/monitors` | En créer un et le démarrer. |
| `GET /v1/monitors/{id}` | Détail de période hérité. Utilisez plutôt `/analytics` : celui-ci mêle une matrice de cellules non filtrée sur tout l'historique aux chiffres de la fenêtre et tronque les citations à 12 domaines et 20 pages. |
| `PATCH /v1/monitors/{id}` | Mettre à jour des champs, ou passer `enabled` pour mettre en pause et reprendre. |
| `DELETE /v1/monitors/{id}` | Supprimer le moniteur et son historique noté. |
| `POST /v1/monitors/{id}/run` | Avancer la prochaine exécution à maintenant. Elle consomme des crédits comme toute exécution. |
| `GET /v1/monitors/{id}/analytics` | **Le contrat de rapport.** Une cohorte, un jeu de filtres, toutes les sections. |
| `GET /v1/monitors/{id}/sources` | Domaines ou pages cités sur la même fenêtre, paginés. |
| `GET /v1/monitors/{id}/citations` | Série quotidienne des citations pour les principaux domaines et pages : les données des graphiques de citations du tableau de bord. |
| `GET /v1/monitors/{id}/results` | Les lignes notées elles-mêmes, en JSON ou CSV, avec filtres et curseur. |
| `GET /v1/monitors/{id}/answers/{taskId}` | La réponse conservée derrière une ligne. |
| `GET /v1/monitors/{id}/prompt` | Détail d'un prompt : sa série, ses sources et ses lignes récentes. |
| `GET /v1/monitors/{id}/alerts` · `POST .../alerts/test` | Seuil d'alerte, état de verrouillage et historique d'envoi ; mettre en file un e-mail de test. |
| `POST /v1/monitors/suggest` | Prompts candidats à partir des informations de marque. N'enregistre rien et ne consomme aucun crédit de tâche. |
| `POST /v1/monitors/research` | Recherche de prompts pour un moniteur : la requête, le prix et le résultat de [Prompt Research](/fr/research/prompt-research), soumis au nom de votre compte. |

Tous utilisent la même clé bearer que le reste de l'API (voir [Authentification](/fr/authentication)). Un moniteur
appartenant à un autre compte répond `404`, pas `403`.

## Créer un moniteur

```bash theme={null}
curl -X POST "$BASE/v1/monitors" \
  -H "Authorization: Bearer $QUERYING_API_KEY" -H "Content-Type: application/json" \
  -d '{
    "name": "Earbud brand tracking",
    "engines": ["CHATGPT", "GEMINI"],
    "prompts": ["best wireless earbuds for commuting", "are cheap earbuds worth it"],
    "aliases": ["Acme Audio", "Acme"],
    "domains": ["example.com"],
    "competitors": [{ "name": "Sony", "aliases": ["Sony"] }],
    "country": "US",
    "intervalHours": 24
  }'
```

`name`, `engines`, `prompts`, `aliases` et `intervalHours` sont obligatoires sur un moniteur de marque ; un moniteur de catégorie prend `category` à la place de `aliases`. Chaque liste accepte un tableau ou une
chaîne unique séparée par des retours à la ligne ; les entrées sont nettoyées, les lignes vides supprimées et les
doublons retirés. `country` choisit le marché pour lequel les moteurs répondent et ne traduit pas les prompts.
`prompts × engines` doit rester inférieur ou égal à la limite `tasksPerRun` de capabilities.

Les moteurs sont les surfaces de prompt planifiables : `CHATGPT`, `GEMINI`, `PERPLEXITY`, `GOOGLE`, `AIMODE`,
`NAVER_AI_BRIEF`, `NAVER_AI_TAB` et l'alias obsolète `NAVER`. `GOOGLE_AIO` et `GOOGLE_AIMODE` sont acceptés et stockés
comme `GOOGLE` et `AIMODE`. Les tâches d'analyse comme `SOURCE_INFLUENCE` ne sont pas des surfaces de prompt et ne
peuvent pas être planifiées sur un moniteur.

Une clé restreinte à certains moteurs ne peut planifier que ceux-ci ; tout autre renvoie `403 KEY_SCOPE_DENIED`. La
limite de moniteurs du compte renvoie `409 MONITOR_LIMIT`.

## L'exécuter, puis lire le rapport

`POST /v1/monitors/{id}/run` rend la prochaine exécution due immédiatement, et les tâches de réponse apparaissent en une
minute environ. Elle est facturée comme une exécution planifiée, et relancer l'appel tant que cette fenêtre est encore
due ne facture pas deux fois.

`GET /v1/monitors/{id}/analytics` est le contrat dont doit provenir chaque élément de votre rapport. Sa fenêtre est
**semi-ouverte et en UTC** (`since` inclus, `until` exclu) et se choisit de l'une de ces deux façons :

| Paramètre | Règle |
| - | - |
| `days` | L'une des valeurs `7`, `30` (par défaut) ou `90`, se terminant maintenant. Incompatible avec `since`/`until`. |
| `since` et `until` | Obligatoires ensemble, instants ISO complets **avec fuseau horaire** (par exemple `2026-09-15T00:00:00Z`). L'intervalle doit être positif, de 90 jours au plus, et pas dans le futur. Un `YYYY-MM-DD` seul est refusé ici : il ne définit pas une fenêtre portable. |

Deux filtres facultatifs s'appliquent à **toutes** les sections à la fois : `engine` (id canonique ou alias public) et
`prompt` (texte exact, jusqu'à 2 000 caractères). Les lignes sont indexées par le texte du prompt : un prompt retiré
ensuite du moniteur reste interrogeable.

Toutes les sections partagent cette cohorte, et l'intervalle précédent a exactement la même durée et les mêmes filtres :
la comparaison se fait à conditions égales.

| Champ | Contenu |
| - | - |
| `window` | `since`, `until`, `previousSince`, `previousUntil`, `timezone` et les `bounds` littérales de la fenêtre. `previousUntil` vaut toujours le `since` de cette fenêtre. |
| `filters` | Les filtres appliqués, résolus : l'id canonique du moteur, le prompt exact, ou `null`. |
| `stats` · `previous` | Comptages et taux pour la fenêtre et pour l'intervalle précédent. |
| `changes` | Variations en points de pourcentage, ou `null` si la comparaison n'est pas fiable (voir plus bas). |
| `engineRates` | Les mêmes taux par moteur, pour repérer un moteur faible sans lire de graphique. |
| `series` | Par jour UTC et par moteur, avec `partial` marquant un jour coupé par le bord de la fenêtre. |
| `brands` | Votre marque (`__you__`) et chaque concurrent suivi, du plus mentionné au moins mentionné, chacun avec son propre `sampleSize` et le taux mesuré sur celui-ci. |
| `voiceSeries` | Les mêmes marques par jour UTC, pour la courbe de tendance. |
| `prompts` | Totaux par prompt, du taux de mention le plus faible au plus élevé, chacun avec ses cellules par moteur. |
| `opportunities` | Cellules où un concurrent a été mentionné et pas votre marque, des plus manquées aux moins manquées. La liste sur laquelle travailler. |
| `quality` | La composition de l'échantillon, et tout ce que les chiffres ne peuvent pas dire. |
| `health` · `healthScope` | L'état d'exécution des tâches encore visibles individuellement : un périmètre récent distinct, jamais inclus dans le dénominateur. |

## Ce que signifient les chiffres

Lisez ceci avant d'étiqueter un panneau de tableau de bord. Les définitions sont le contrat publié, et
`GET /v1/monitors/capabilities` les renvoie sous `metrics` pour qu'un client puisse les afficher à côté des chiffres.

* **`mentionRate`** pour la fenêtre, ses groupes par moteur et ses groupes par cellule vaut
  `100 × réponses avec mention / réponses notées`. Il est pondéré par les réponses, pas une moyenne des taux par moteur :
  un moteur très actif ne peut pas être écrasé par un moteur peu actif. (Le taux propre d'une marque a son propre
  dénominateur, expliqué ci-dessous.)
* **`citationRate`** a la même forme pour les réponses qui ont cité l'un de vos domaines enregistrés. Sans domaine
  enregistré, il vaut toujours zéro, car le suivi des citations est désactivé.
* **Le taux d'une marque se divise par son propre `sampleSize`, pas par le total de la fenêtre.** 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. Ajoutez un concurrent aujourd'hui et son premier rapport couvre les réponses qui l'ont mesuré : l'historique
  antérieur ne compte pas contre lui. Une marque sans réponse éligible affiche `mentionRate: null`, pas 0 %, car 0 % se
  lirait comme une vraie disparition.
* **`shareOfVoice`** dans `brands` vaut `100 × mentions de cette marque / toutes les mentions des marques suivies` sur la
  fenêtre : les parts d'une fenêtre totalisent donc 100. 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é. Le `shareOfVoice` de
  l'endpoint de détail hérité est l'ancienne vue de pénétration des réponses, où chaque marque est comptée par rapport
  aux réponses collectées et où le total peut dépasser 100 : ne mélangez pas les deux dans un même graphique.
* **`competitorOnly`** (et la liste `opportunities`) compte les réponses qui ont nommé un concurrent configuré alors que
  votre marque était absente. C'est l'écart sur lequel vous pouvez agir.
* **Les taux sont nullables, pas nuls.** Aucune réponse dans la fenêtre donne `null` ; un taux de zéro signifie qu'il y
  a eu des réponses et qu'aucune ne correspondait.
* **Une observation terminée sans réponse compte comme non mentionnée.** Elle reste dans le dénominateur, et
  `quality.noAnswerObservations` indique combien il y en a eu. 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 de devenir silencieusement une absence,
  et `quality` ne la reconstruit jamais comme telle (`historicalFailures` vaut toujours `null`).
* **Les variations sont masquées quand elles induiraient en erreur.** `changes` et le `mentionRateChangePp` par cellule
  valent `null`, et `quality.comparable` vaut `false`, lorsqu'une période n'a aucune réponse (`insufficient_periods`),
  lorsque des lignes ont été notées avant l'existence du contexte de notation (`legacy_scoring_unknown`), ou lorsque la
  définition de notation a changé entre les périodes (`scoring_definitions_changed`). Les lignes historiques gardent
  les définitions avec lesquelles elles ont été notées (`quality.scoring`) : modifier vos alias ou concurrents ne
  réécrit jamais le passé. Seule exception : la lecture mensuelle des concurrents décrite plus haut.
* **La taille d'échantillon est publiée.** `quality.lowSample` est true en dessous de 30 réponses notées,
  `quality.missingCells` compte les cellules prompt × moteur configurées encore sans réponse, et `quality.partialDays`
  nomme les jours UTC que la fenêtre coupe en deux : le comptage plus faible d'un jour partiel est arithmétique, pas un déclin.

`position` sur une ligne notée est l'**offset de caractère** de la première occurrence d'alias dans le texte de la
réponse : un indicateur de mise en avant, pas un classement. Il vaut `null` quand la marque est absente, si bien que `0`
n'a jamais à signifier « absent ».

## D'où viennent les réponses

`GET /v1/monitors/{id}/sources` répond à la question « quelles pages remportent ces prompts », avec la même fenêtre et
les mêmes filtres que le rapport, en comptant des **réponses distinctes** plutôt que des citations brutes : une page
citée trois fois dans une réponse compte une fois.

| Paramètre | Règle |
| - | - |
| `groupBy` | `domain` (par défaut, hôte sans `www.`) ou `page` (URL complète avec son libellé). |
| `limit` | 1 à 100, 20 par défaut. |
| `cursor` | Le `nextCursor` de la réponse précédente, renvoyé tel quel. `null` termine la liste. |
| `days` / `since`+`until` / `engine` / `prompt` | Exactement comme pour le rapport. |

Chaque ligne porte `citations` et `prompts` (tous deux des comptages de réponses distinctes), `own` pour vos domaines
enregistrés, et un `evidenceTaskId` que vous pouvez ouvrir avec l'endpoint des réponses. Il n'y a pas de coupe
silencieuse aux N premiers : chaque domaine ou page de la fenêtre est accessible en suivant le curseur.

## Citations dans le temps

`GET /v1/monitors/{id}/citations` renvoie les données des graphiques de citations du tableau
de bord : le total quotidien des citations sur la fenêtre, et une série quotidienne pour chaque
domaine et page principal. Il lit seulement les résultats enregistrés et ne consomme donc aucun crédit.

| Paramètre | Règle |
| - | - |
| `days` | `7`, `30` ou `90`, `30` par défaut. |
| `since`+`until` | Une fenêtre fixe de 90 jours au plus, comme pour le rapport. S'ils sont fournis, `days` n'est qu'un libellé. |
| `engine` / `prompt` | Comme pour le rapport. |
| `kind` | `all` (par défaut), `owned`, `editorial`, `pr_wire`, `institution`, `reviews`, `commerce`, `social`, `other`. |
| `q` | Filtre les domaines par nom, ou les pages par URL. 200 caractères au plus. |
| `offset` | 0–10 000. Chaque liste renvoie 20 lignes. |

Ici, une citation est une page apparaissant dans une réponse : la même page deux fois dans une
réponse compte une seule fois. `/sources` compte les réponses distinctes, ses chiffres peuvent
donc différer.

| Champ | Signification |
| - | - |
| `totals` | `answers`, `citedAnswers`, `citations` et `ownedCitations` pour la fenêtre. |
| `days` | Une entrée par jour UTC mesuré avec `answers`, `citations` et `ownedCitations`. Un jour avec des réponses mais sans citation apparaît avec `citations: 0` ; un jour sans réponse est absent. |
| `domains` / `pages` | Les 20 premiers à l'`offset` courant, chacun avec `kind`, `owned`, `citations`, `answers`, `prompts` et une série `daily` de `{day, citations}`. `daily` ne liste que les jours avec des citations. |
| `types` | Citations et domaines distincts par `kind`, sur toutes les sources. |
| `pagination` | `offset`, `limit`, `totalDomains`, `totalPages`. |

La part d'une source est son `citations` divisé par `totals.citations`. `kind`, `q` et
`offset` ne font que restreindre les listes ; `totals`, `days` et `types` couvrent toujours
toutes les sources de la fenêtre.

```bash theme={null}
curl "$BASE/v1/monitors/$MONITOR_ID/citations?days=30&kind=owned" \
  -H "Authorization: Bearer $QUERYING_API_KEY"
```

## Exporter les lignes notées

`GET /v1/monitors/{id}/results` renvoie les lignes elles-mêmes, pour un chargement en entrepôt de données, un support
hebdomadaire ou un tableur.

| Paramètre | Règle |
| - | - |
| `since` · `until` | Semi-ouverte, par défaut les 30 derniers jours se terminant maintenant. `since` accepte aussi un `YYYY-MM-DD` seul (lu comme `00:00:00Z`) pour compatibilité avec l'export d'origine ; l'endpoint de rapport, non. |
| `engine` · `prompt` | Mêmes filtres que le rapport. |
| `mentioned` · `cited` | `true`/ `false`. `mentioned=false` est la vue des écarts concurrentiels. |
| `competitor` | Un nom exact de concurrent configuré ; conserve les réponses dont la liste de concurrents stockée le contient. |
| `includeEvidence` | Ajoute `answerText`, `sources` et `scoringContext` à chaque ligne, et abaisse la taille maximale de page. |
| `limit` | 1 à 10 000, 10 000 par défaut. Avec `includeEvidence`, la valeur par défaut et le maximum sont 100. |
| `format` | `json` (par défaut) ou `csv`. |
| `cursor` | Le `nextCursor` de la réponse précédente. |

La pagination est un keyset sur `(ranAt, id)` à la microseconde près : des lignes partageant un horodatage ne peuvent
être ni sautées ni répétées. Pour rendre l'extraction reproductible : **envoyez des `since` et `until` explicites,
gardez-les fixes, et suivez `nextCursor` jusqu'à ce qu'il vaille `null`.** Changer la fenêtre entre deux pages peut
sauter ou répéter des lignes. Traitez le curseur comme opaque : il est renvoyé et réémis, jamais construit.

Avec `format=csv`, la réponse est en `text/csv` (UTF-8 avec BOM, pour qu'Excel l'ouvre correctement) et l'état de
pagination passe dans les en-têtes, car un corps CSV n'a nulle part ailleurs où le placer :

| En-tête | Signification |
| - | - |
| `x-next-cursor` | Le curseur de la page suivante ; vide sur la dernière page. |
| `x-result-truncated` | `true` quand plus de lignes correspondaient que ce que cette page a renvoyé. |
| `x-result-since` · `x-result-until` | La fenêtre résolue, pour qu'un export repris puisse la figer. |

Les colonnes sont `ran_at, monitor, engine, prompt, mentioned, cited, position, competitors, task_id`, plus
`answer_text, sources, scoring_context` quand `includeEvidence=true` (`sources` et `scoring_context` en texte JSON dans
leurs cellules). Les cellules qui pourraient être interprétées comme une formule de tableur sont neutralisées avant
écriture : un texte tiers ne peut pas devenir une formule dans votre feuille.

## Lire la réponse derrière un chiffre

`GET /v1/monitors/{id}/answers/{taskId}` renvoie la preuve conservée pour une ligne :

* `answerText` : la réponse telle que le moteur l'a donnée, en markdown si disponible, **8 000 caractères au plus**,
  coupée avec des points de suspension si elle était plus longue.
* `sources` : les citations dans l'ordre du moteur, chacune avec son libellé et sa position (à partir de 1) dans cette liste.
* `aliases` et `competitors` : ce à quoi cette ligne a été comparée, pour que la mention puisse être vérifiée plutôt que crue sur parole.
* `scoringContext` : la définition exacte utilisée, avec un hash `version`, l'heure de notation, `answerPresent` et
  `evidenceTruncated` quand le texte ci-dessus a été coupé.

Les lignes notées avant que le contexte de notation ne soit stocké renvoient `scoringKnown: false` avec les alias
actuels du moniteur et un `evidenceTruncated` à `null`. `answerText` vaut `null` quand le moteur n'a renvoyé aucun texte de réponse.

## Erreurs sur cette surface

L'enveloppe est la même que partout ailleurs (voir [Erreurs](/fr/concepts/errors)) ; les codes propres au suivi sont :

| Code | Statut | Quand |
| - | - | - |
| `VALIDATION_ERROR` | 400 | Fenêtre invalide (`days` mêlé à `since`/`until`, intervalle de plus de 90 jours, instant sans fuseau horaire), moteur inconnu, prompt trop long, `limit` hors plage, ou rapport trop volumineux à agréger : réduisez la fenêtre, le moteur ou le prompt. |
| `MISSING_API_KEY` / `UNAUTHORIZED` | 401 | Pas de clé, ou une clé qui n'appartient pas à ce compte. |
| `KEY_SCOPE_DENIED` | 403 | Les moteurs autorisés de la clé ne couvrent pas ceux du moniteur. |
| `NOT_FOUND` | 404 | Aucun moniteur de ce type pour cette clé (le moniteur de quelqu'un d'autre apparaît de la même façon), ou aucune ligne notée avec cet id de tâche. |
| `MONITOR_LIMIT` | 409 | Le compte détient déjà le nombre maximal de moniteurs. |
| `RATE_LIMITED` | 429 | Suggestions de prompts (une toutes les 20 secondes, 30 par heure) ou e-mails d'alerte de test (trois par moniteur toutes les cinq minutes). |
| `SUGGEST_FAILED` | 400 / 502 / 503 | Les suggestions de prompts ont été refusées pour cette marque, le service de suggestion a échoué, ou il n'est pas configuré sur ce déploiement. |

## Un agent dans la boucle

Une séquence pratique pour un agent ou un script, avec uniquement les endpoints de cette page. Elle est illustrative :
remplacez la clé, l'id du moniteur et la fenêtre par les vôtres.

1. `GET /v1/monitors/capabilities` : lisez les moteurs, les prix et les limites avant de dépenser quoi que ce soit.
2. `GET /v1/monitors` : réutilisez un moniteur existant pour le sujet et le marché, ou `POST /v1/monitors` pour en
   créer un (en appelant éventuellement d'abord `POST /v1/monitors/suggest` et en modifiant les candidats).
3. `POST /v1/monitors/{id}/run` : si vous avez besoin de réponses avant la prochaine fenêtre planifiée.
4. `GET /v1/monitors/{id}/analytics?days=30&engine=CHATGPT` : lisez d'abord `quality` (`comparable`, `lowSample`,
   `missingCells`, `partialDays`), puis les chiffres. Interrogez jusqu'à ce que `health.pending` se stabilise et que
   `quality.sampleSize` cesse d'augmenter.
5. `GET /v1/monitors/{id}/sources?days=30&groupBy=page` : parcourez les pages avec `nextCursor` pour trouver celles qui remportent les prompts.
6. `GET /v1/monitors/{id}/answers/{taskId}` : ouvrez la réponse derrière la première entrée de `opportunities` avant de décider quoi que ce soit.
7. `GET /v1/monitors/{id}/results?since=...&until=...&includeEvidence=true&format=csv` : exportez la même fenêtre en
   suivant `x-next-cursor` jusqu'à ce qu'il soit vide.

Les mêmes opérations sont exposées aux agents sous forme d'outils MCP (`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`,
`test_monitor_alert`). Les écritures sont annotées comme des mutations, et `create_monitor` et `run_monitor` précisent
qu'ils consomment des crédits avant d'être appelés.

## Limites

| Limite | Valeur |
| - | - |
| Moniteurs par compte | 20 |
| Tâches par exécution | 200 (`prompts × engines`) |
| Prompts par moniteur | 100 |
| Longueur d'un prompt | 2 000 caractères |
| Alias de marque | 20 |
| Domaines enregistrés | 20 |
| Concurrents | Moniteur de marque : 10 ajoutés par vous, plus 15 trouvés au maximum. Moniteur de catégorie : 25 ajoutés par vous, plus 25 trouvés au maximum |
| Nom de la catégorie | 80 caractères |
| Sous-domaines par moniteur de catégorie | 30, de 60 caractères au maximum chacun |
| Intervalle | 1 à 168 heures |
| Fenêtre de rapport | 90 jours |
| Page de résultats | 10 000 par défaut, 10 000 au maximum ; 100 avec preuves |
| Page de sources ou de preuves | 100 |

Consultez les [tarifs](https://querying.ai/fr/pricing) et la [référence des moteurs](/fr/engines/overview) avant d'augmenter le volume.