Concepts clés

Les règles communes à tous les endpoints : filtres, définitions des métriques, sorties JSON et CSV, codes d’erreur et gestion des versions.

Filtres et paramètres communs

  • project_id obligatoire pour tous les endpoints liés à un projet.
  • metrics ou metric : valeurs séparées par des virgules parmi mentions, citations, responses, mention_rate (or visibility), citation_rate, ai_visibility_score, avg_position, avg_mention_position, sentiment_very_positive, sentiment_positive, sentiment_neutral, sentiment_negative, sentiment_very_negative, net_sentiment
  • granularity : day|week|month (les semaines commencent le lundi)
  • Période : soit range (en jours), soit from et to (ISO8601). Si vous envoyez to, from est obligatoire. Valeurs par défaut avec from/to : from absent = il y a 30 jours (début de journée) ; to absent = maintenant (fin de journée).
  • Filtres : model, collection_id (ID du tag), prompt (ID du prompt), country_code, language_code, competitors (ID séparés par des virgules)
  • include_project (true par défaut) : définissez false pour exclure votre projet (seuls les concurrents sont renvoyés).

Définitions des métriques

Ces définitions correspondent exactement aux calculs de la Vue d’ensemble de l’application.

  • mentions : sommes quotidiennes de mentions_count. Pour week/month, nous calculons le TOTAL DE LA PÉRIODE (du lundi au dimanche pour les semaines) et répétons ce même total pour chaque jour de la période. Si le total d’une période vaut 0, nous « reportons » le dernier total de période non nul (report persistant).
  • citations : nombre calculé au niveau de la réponse, qui inclut les citations visibles et les références à des sources en arrière-plan. Chaque acteur est compté au plus une fois par réponse. Mêmes règles de total par période et de report de la dernière valeur que pour les mentions.
  • responses : nombre total d’exécutions de prompts (appels API aux LLM). Utilise le nombre d’exécutions au niveau du projet, quel que soit l’acteur. • day : somme quotidienne. • week/month : total de la période (sans report de la dernière valeur ; les jours sans exécution affichent 0).
  • Taux de mention mention_rate (visibility est aussi accepté) : pourcentage par acteur, avec pour dénominateur les exécutions au niveau du projet, sous les mêmes filtres (mentions_count / prompt_executions_count × 100). • day : calcul du ratio quotidien. • week/month : calcul du ratio des sommes de la période (Σ mentions / Σ exécutions), répété pour chaque jour de la période. Si le dénominateur de la période vaut 0, la dernière valeur non null est reportée.
  • citation_rate : pourcentage des réponses qui contiennent une citation visible ou en arrière-plan pour l’acteur (citations_count / prompt_executions_count × 100). • day : ratio quotidien. • week/month : ratio des sommes de la période, avec report de la dernière valeur, comme pour le taux de mention.
  • AI Visibility Score ai_visibility_score : score pondéré par la position, qui tient compte de la place de la mention. Chaque réponse qui mentionne l’acteur rapporte 100 ÷ position points (position 1 = 100, position 2 = 50, position 3 = 33,33, etc.), et ces points sont divisés par les exécutions de suivi (une par jour, par semaine ou par mois selon la fréquence de suivi du compte) qui comptent des réponses avec les mêmes filtres : le score correspond ainsi à une exécution de suivi moyenne. Ce n’est pas un pourcentage, il n’est pas plafonné à 100 et il n’augmente pas avec la durée de la fenêtre. Un prompt ajouté en milieu de semaine reçoit sa réponse un autre jour, mais appartient à l’exécution de suivi de cette semaine. Pour les concurrents, on divise par les exécutions de suivi du projet, afin que leurs scores soient comparables au vôtre. • day : les points du jour. • week/month : les points de la période divisés par les exécutions de suivi qu’elle contient, répétés pour chaque jour de la période ; si une période ne compte aucune réponse, nous « reportons » la valeur de la dernière période (report persistant). • /metrics/summary : les points de la fenêtre divisés par ses exécutions de suivi, soit le chiffre affiché dans la Vue d’ensemble.
  • avg_position : position moyenne des citations visibles. Les citations en arrière-plan n’ont pas de position visible et sont exclues. • day : moyenne quotidienne hors valeurs null. • week/month : moyenne sur la période (valeurs null ignorées), puis report de la dernière valeur connue sur les jours sans données, conformément au lissage du graphique de la Vue d’ensemble.
  • avg_mention_position : position moyenne de la marque lorsqu’elle est mentionnée dans les réponses de l’IA (position 1 = mentionnée en premier, position 2 = en deuxième, etc.). Plus la valeur est basse, mieux c’est. • day : moyenne quotidienne hors valeurs null. • week/month : moyenne sur la période, avec report de la dernière valeur.
  • Métriques de sentiment sentiment_very_positive,sentiment_positive,sentiment_neutral,sentiment_negative,sentiment_very_negative : pour chaque acteur et chaque jour, pourcentage des sentiments de cette catégorie sur l’ensemble des sentiments de l’acteur. • day : ratio quotidien (bucket_count / total_sentiments * 100). Les jours sans sentiment renvoient null. • week/month : nous calculons un ratio des sommes de la période (Σ bucket / Σ total * 100) et répétons ce pourcentage pour chaque jour de la période. Si le dénominateur de la période vaut 0, nous reportons la dernière valeur non null (report persistant), conformément au lissage de la Vue d’ensemble.
  • Score de sentiment net net_sentiment : pour chaque acteur et chaque jour, le score va de -100 à 100 et se calcule ainsi : ((very_positive + positive) − (negative + very_negative)) / total_sentiments × 100, où total_sentiments est la somme des effectifs des cinq catégories de sentiment. Le calcul utilise directement les effectifs, sans arrondir au préalable les pourcentages de chaque catégorie, et arrondit le score obtenu à deux décimales. • day : calcule le score à partir des effectifs du jour et renvoie null si aucun sentiment n’est classé. • week/month : calcule un score par période à partir des effectifs cumulés sur cette période ; l’API renvoie un point par période. Si une période ne compte aucun sentiment classé, l’API reporte le dernier score non null. Dans l’API REST, les périodes vides en début de série valent 0. • /metrics/summary : calcule un score à partir des effectifs cumulés sur toute la fenêtre, soit le score affiché dans l’application pour les mêmes filtres, et renvoie null si la fenêtre ne contient aucun sentiment classé.

Dans /metrics/summary, total est une somme pour les métriques de comptage et, pour ai_visibility_score, les points de la fenêtre divisés par ses exécutions de suivi. Les taux, positions et sentiments (visibility, citation_rate, avg_position, avg_mention_position, net_sentiment et les parts de sentiment) sont agrégés sur l’ensemble de la fenêtre, soit le chiffre affiché dans l’application pour les mêmes filtres, jamais une moyenne des valeurs par période.

Formats de sortie pour les outils de BI

Les endpoints de lecture renvoient par défaut du JSON imbriqué, pratique pour le code mais illisible pour les outils de BI. Passez le paramètre facultatif output pour obtenir les mêmes données sous forme de tableau rectangulaire, directement exploitable par Tableau, Excel, Google Sheets ou un outil de chargement d’entrepôt de données.

  • output omis (par défaut) : le JSON imbriqué documenté pour chaque endpoint. Inchangé : les intégrations existantes ne sont pas affectées.
  • output=flat : les mêmes métadonnées, plus columns (noms des colonnes, dans l’ordre), rows (un objet à plat par ligne) et row_count.
  • output=csv : les mêmes lignes au format text/csv, avec columns comme ligne d’en-tête.

Pris en charge par /metrics/timeseries, /metrics/summary, /metrics/sov, /metrics/prompt_summary, /metrics/top_sources, les séries /search_console/* et les endpoints /dimensions/* qui renvoient une liste. Les endpoints dont le payload n’est pas un tableau unique (/metrics/agent_traffic, /metrics/ai_traffic, /search_console/summary, /dimensions/models, /dimensions/locales) rejettent output au lieu de l’ignorer.

/metrics/sov accepte aussi view=over_time (par défaut), view=current ou view=breakdown : sa réponse contient plusieurs structures différentes, et un tableau ne peut en contenir qu’une à la fois.

Colonnes par endpoint

Endpoint Columns
/metrics/timeseries date, actor_type, actor_id, actor_name, actor_domain, metric, value
/metrics/summary actor_type, actor_id, actor_name, actor_domain, metric, aggregation, total, min, max, last
/metrics/sov date, actor_type, actor_id, actor_name, actor_domain, share
/metrics/sov?view=current actor_type, actor_id, actor_name, actor_domain, share
/metrics/sov?view=breakdown rank, actor_type, actor_id, actor_name, actor_domain, share, others
/metrics/prompt_summary, /metrics/top_sources, /search_console/timeseries|queries|pages, /dimensions/* The keys of the endpoint's own data rows

Exemple

GET /api/v1/metrics/timeseries?project_id=1&range=30&metrics=mentions&output=csv

date,actor_type,actor_id,actor_name,actor_domain,metric,value
2025-01-01,project,1,My Brand,mybrand.com,mentions,10
2025-01-01,competitor,2,Competitor A,competitor.com,mentions,5

Remarques :

  • Les erreurs sont toujours renvoyées en JSON, jamais en CSV, pour qu’un échec ne soit jamais pris pour des données.
  • Les pourcentages restent sur l’échelle brute de 0 à 100, exactement comme dans la réponse JSON.
  • Les cellules de texte qui commencent par le signe égal, plus ou moins, ou par une arobase sont échappées pour que les tableurs ne les exécutent pas comme des formules.
  • Les endpoints paginés renvoient aussi leurs métadonnées de pagination dans les en-têtes de réponse X-Total-Count, X-Page et X-Per-Page, qu’un corps CSV ne peut pas contenir.
  • La sortie tabulaire est limitée à 200 000 lignes. Au-delà, réduisez la plage de dates, demandez moins de métriques ou utilisez granularity=week.
  • Les endpoints sans sortie tabulaire refusent output avec ERR_INVALID_PARAM au lieu de l’ignorer.

Erreurs

Les erreurs suivent une structure JSON homogène. Basez votre traitement sur le champ code. Le champ message contient le détail de l’erreur lorsqu’il est disponible, sinon une valeur par défaut comme missing_authorization :

Code HTTP Signification
ERR_MISSING_AUTH 401 En-tête Authorization manquant ou mal formé
ERR_INVALID_API_KEY 401 Jeton non reconnu
ERR_REVOKED_API_KEY 403 Clé révoquée
ERR_INSUFFICIENT_SCOPE 403 Une clé ou un jeton OAuth en lecture seule a été utilisé pour une écriture
ERR_INSUFFICIENT_PERMISSION 403 L’utilisateur associé à la clé n’est pas autorisé à effectuer cette action (par exemple, un membre de l’équipe sans l’autorisation nécessaire)
ERR_KEY_PROJECT_SCOPED 403 Une clé limitée à certains projets a été utilisée pour une opération portant sur tout le compte
ERR_PLAN_REQUIRED 403 Le forfait du compte n’inclut pas cet endpoint
ERR_INTEGRATION_UNAVAILABLE 403 Cette fonctionnalité n’est pas disponible pour ce compte ou sur ce domaine
ERR_ACCOUNT_INACTIVE 403 L’abonnement du compte a pris fin, ou le compte est en pause en raison d’un renouvellement impayé
ERR_SEARCH_CONSOLE_ACCESS_REVOKED 403 Google a révoqué l’accès du projet à la Search Console ; reconnectez la propriété
ERR_CMS_ACCESS_REVOKED 403 WordPress n’accepte plus le mot de passe d’application enregistré, ou l’utilisateur associé ne peut pas rédiger d’articles ; reconnectez le site
ERR_WEB_ANALYTICS_ACCESS_REVOKED 403 Le fournisseur d’analyse web a refusé les identifiants enregistrés ; reconnectez-le
ERR_DRAFT_NOT_FOUND 404 Brouillon de projet introuvable, ou créé par un autre utilisateur
ERR_PROJECT_NOT_FOUND 404 project_id inaccessible pour cet utilisateur
ERR_NOT_FOUND 404 Ressource introuvable
ERR_SEARCH_CONSOLE_NOT_CONNECTED 404 Aucune propriété Google Search Console n’est connectée au projet
ERR_CMS_NOT_CONNECTED 404 Aucun site WordPress n’est connecté au projet
ERR_AI_TRAFFIC_NOT_CONNECTED 404 Aucun outil d’analyse web n’est connecté au projet pour le trafic IA
ERR_WEB_ANALYTICS_NOT_CONNECTED 404 Aucun outil d’analyse web n’est connecté au projet
ERR_AGENT_TRAFFIC_NOT_CONNECTED 404 Aucune source de trafic des agents n’est connectée au projet
ERR_STALE_CONTENT 409 La tâche GEO Writer a été régénérée après la valeur result_version envoyée avec la modification ; rien n’a été enregistré
ERR_DRAFT_STATE 422 Brouillon de projet expiré, déjà finalisé ou auquel il manque une étape précédente (le message précise laquelle)
ERR_CMS_REJECTED 422 WordPress a refusé la requête, le site redirige désormais vers une autre adresse ou il n’est plus joignable en toute sécurité ; inutile de réessayer
ERR_WEB_ANALYTICS_INVALID_QUERY 422 L’outil d’analyse web a rejeté la requête (le message contient son erreur de validation)
ERR_INVALID_RANGE 422 Plage de dates Search Console avec from postérieur à to
ERR_INVALID_PARAM 422 Échec de la validation (voir le message)
ERR_LIMIT_REACHED 422 Limite de projets, de prompts, de rapports GEO techniques ou de recommandations atteinte (le message précise laquelle)
ERR_QUOTA_EXCEEDED 422 Plafond de concurrents, de tâches GEO Writer ou d’abonnements webhook atteint (le message précise lequel)
ERR_RATE_LIMITED 429 Limite de requêtes dépassée ; attendez le nombre de secondes indiqué dans Retry-After
ERR_GENERATION_FAILED 502 Une génération par l’IA a échoué ; relancez la requête
ERR_SEARCH_CONSOLE_UPSTREAM 503 Google Search Console est indisponible ou son quota est dépassé ; attendez le nombre de secondes indiqué dans Retry-After
ERR_CMS_UPSTREAM 503 Le site WordPress est injoignable ou a mis trop de temps à répondre ; réessayez plus tard
ERR_WEB_ANALYTICS_UPSTREAM 503 L’outil d’analyse web est indisponible, ou le quota de requêtes en direct du projet est épuisé ; attendez le nombre de secondes indiqué dans Retry-After

Structure du corps d’erreur :

Cas 422 typiques :

  • invalid metrics : seules les valeurs mentions, citations, responses, mention_rate (or visibility), citation_rate, ai_visibility_score, avg_position, avg_mention_position, sentiment_very_positive, sentiment_positive, sentiment_neutral, sentiment_negative, sentiment_very_negative, net_sentiment sont autorisées.
  • invalid granularity : doit être day|week|month.
  • from/to must be ISO8601 ou from is required with to.
  • range is required lorsque ni from ni to ne sont envoyés.
  • unknown competitor ids: ... : ID introuvables dans le projet.

Versions et limites de requêtes

Version actuelle : v1. Les futures modifications incompatibles changeront le chemin (par exemple /api/v2).

Limite de requêtes : 300 requêtes par minute et par clé API, appels REST et MCP confondus. Un client MCP connecté via OAuth bénéficie de la même limite de 300 requêtes par minute. Il n’existe aucun quota mensuel ou quotidien de requêtes : les budgets par minute sont les seules limites de requêtes. Contactez-nous si une clé a besoin d’une limite par minute plus élevée.

Les écritures (POST, PATCH, PUT et DELETE) sont aussi décomptées d’un second budget de 60 requêtes par minute et par clé API. L’endpoint MCP et POST /web_analytics/query, qui ne fait que lire, en sont exemptés.

Chaque réponse à une requête effectuée avec une clé API comporte X-RateLimit-Limit, X-RateLimit-Remaining et X-RateLimit-Reset (l’horodatage Unix, en secondes, de la fin de la fenêtre d’une minute en cours) pour ce budget par clé. Le budget d’écriture n’a pas d’en-têtes propres.

Une requête qui dépasse l’un ou l’autre budget reçoit une réponse HTTP 429 avec le code d’erreur ERR_RATE_LIMITED. Son en-tête Retry-After indique la durée de la fenêtre du budget en secondes (60) : attendre ce délai suffit donc toujours à repasser sous la limite. En cas de dépassement du budget par clé, la réponse 429 contient aussi les trois en-têtes X-RateLimit-*.

Les requêtes qui utilisent les quotas du forfait restent décomptées de ces quotas, par exemple les nouveaux prompts (qui consomment aussi le quota de réponses de l’IA du cycle de suivi), les projets, les concurrents par projet, les tâches GEO Writer du mois, les exécutions manuelles d’audits GEO et les projets de pitch du mois. GET /account indique ce qu’il reste de chacun.