Aller au contenu principal

Audits GEO

Trois appels couvrent le cycle d'un audit : lancer, suivre le statut, lire le détail. Tous exigent une clé cm_ d'un forfait payant (voir Forfaits). Dans l'API, une marque est un projet : son id est le :id des routes. Lancer un audit demande en plus une clé avec le scope write.

Un audit tourne sur les prompts, pas sur les mots-clés

L'audit pose aux moteurs IA les prompts actifs de la marque. Ils se créent avec POST /projects/:id/prompts, dans le dashboard ou via les outils MCP create_prompts et import_prompts, jamais via /keywords. Sans prompt actif, le lancement est refusé avec 400.


POST /projects/:id/audits​

Lance un audit GEO. Scope write requis.

Corps de la requête (tous les champs sont facultatifs) :

{
"providers": ["chatgpt", "claude", "gemini", "perplexity", "google-aio"]
}
ChampDéfautDescription
providersles 5 moteurs de base, voir plus basMoteurs à interroger, parmi chatgpt, claude, gemini, perplexity, grok, google-aio, siri, deepseek, meta, mistral. Mêmes valeurs que l'outil MCP run_audit. Toujours respecté tel quel
regionfrRepli seulement : chaque prompt est posé dans la langue et le pays de son marché. region ne sert qu'à un prompt dont le marché a été supprimé
modelaucunAncien champ, un seul modèle (par exemple gpt-4.1). Ignoré si providers est présent, 400 si le modèle est inconnu
keywordsaucunAccepté mais ignoré : ne choisit pas les prompts, la réponse le signale dans warnings

Moteurs par défaut, budget et coupe​

Le forfait payant donne 250 requêtes IA par audit, de quoi poser ses 50 prompts par marque aux 5 moteurs de base. Chaque moteur coûte une requête par prompt, google-aio compris : tous les prompts actifs tournent donc sur les 5 moteurs de base. Avec plus de moteurs, le budget couvre moins de prompts, 25 sur les 10 moteurs.

Le forfait payant compte aussi 5 audits manuels par semaine et par marque, remis à zéro le lundi à 00:00 UTC. Un audit sur N moteurs n'est accepté que s'il en reste au moins N.

  • Sans providers ni model, l'audit part des 5 moteurs de base dans cet ordre de priorité : chatgpt, claude, gemini, perplexity, google-aio. Il garde tous les prompts actifs et retire des moteurs en partant de la fin de la liste jusqu'à ce que tout tienne dans la limite et dans les audits manuels restants. Les moteurs retirés sont nommés dans warnings. Si même chatgpt seul ne couvre pas tous les prompts, il tourne seul sur ceux qui tiennent et warnings le dit.
  • Avec providers, les moteurs demandés tournent tels quels. Si les prompts ne tiennent pas tous, l'audit garde les plus anciens, dans l'ordre de création, et laisse les autres de côté. La lecture de l'audit le dit avec promptsConfigured, promptsRun et warnings.

Réponse (201 Created) :

{
"data": {
"auditId": "3f6c0d52-1b9e-4c5a-9a53-0c7f3d2a1e44",
"jobId": "b2d1c7e0-5a41-4a6e-8f1d-6a0b9c3e7f10",
"engines": ["chatgpt", "claude", "gemini", "perplexity", "google-aio"]
},
"warnings": []
}

data.engines donne les moteurs qui tournent vraiment. Si un audit lancé dans la dernière heure tourne encore sur la marque, aucun second audit n'est créé : la réponse est aussi un 201, avec l'auditId de l'audit en cours, jobId: null, reused: true, ses moteurs, et un avertissement si les providers envoyés diffèrent.

StatutCas
201Audit créé, ou audit déjà en cours renvoyé
400providers invalide (vide ou moteur inconnu) ou model inconnu. Un corps qui n'est pas du JSON n'est pas refusé : il vaut un corps vide et l'audit part avec les moteurs par défaut. code: "prompts_required" : aucun prompt actif. code: "project_not_ready" : onboarding non terminé
403Clé sans scope write, forfait sans accès API, ou code: "plan_required" : forfait sans audit manuel ou moteur hors forfait
404Marque introuvable dans votre organisation
429code: "quota_exceeded" : audits manuels de la semaine épuisés, ou moins d'audits restants que de moteurs, avec Retry-After en secondes jusqu'au lundi 00:00 UTC suivant. Sans code : plus de 10 lancements en une minute avec la même clé, Retry-After dit quand réessayer
500code: "unavailable" : le quota n'a pas pu être lu, réessayez. Sans code : Failed to start audit, erreur inattendue

GET /projects/:id/audits​

Liste les audits de la marque, du plus récent au plus ancien, quel que soit leur statut. C'est l'appel pour suivre un audit lancé : cherchez son id et regardez status.

Réponse (200 OK) :

{
"data": [
{
"id": "3f6c0d52-1b9e-4c5a-9a53-0c7f3d2a1e44",
"score": 47,
"status": "COMPLETED",
"duration": 157669,
"created_at": "2026-10-13T16:23:30Z",
"completed_at": "2026-10-13T16:26:08Z",
"technical_details": { "model": "chatgpt,claude,gemini,perplexity,google-aio" },
"provider_scores": { "OPENAI": 62, "ANTHROPIC": 46, "GOOGLE": 49, "PERPLEXITY": 48, "GOOGLE_AIO": 43 },
"prompts_configured": 35,
"prompts_run": 35,
"warnings": [],
"source": "manual",
"is_automatic": false
}
]
}

status vaut PENDING, RUNNING, COMPLETED ou FAILED. completed_at reste null tant que l'audit n'est ni COMPLETED ni FAILED. score vaut 0 jusqu'à la fin. prompts_configured et prompts_run disent combien de prompts étaient actifs et combien ont vraiment tourné, warnings le dit en clair quand ils diffèrent.


GET /projects/:id/audits/:auditId​

Le détail complet d'un audit : une ligne par couple prompt et moteur, avec la réponse du moteur, et des statistiques calculées.

Réponse (200 OK), champs principaux :

{
"data": {
"id": "3f6c0d52-1b9e-4c5a-9a53-0c7f3d2a1e44",
"score": 47,
"status": "COMPLETED",
"currentProgress": 100,
"providerScores": { "OPENAI": 62, "ANTHROPIC": 46 },
"promptsConfigured": 35,
"promptsRun": 35,
"partial": true,
"failedAnswerCount": 7,
"createdAt": "2026-10-13T16:23:30Z",
"completedAt": "2026-10-13T16:26:08Z",
"project": { "id": "…", "name": "…", "url": "https://exemple.com" },
"analytics": {
"totalQueries": 175,
"citedQueries": 37,
"citationRate": 21,
"providerBreakdown": [{ "provider": "OPENAI", "cited": 16, "total": 35, "rate": 46 }]
},
"queries": [
{
"id": "…",
"prompt": "Quels sont les programmes immobiliers neufs à Bordeaux en 2026 ?",
"provider": "OPENAI",
"cited": true,
"position": 1,
"topic": { "id": "…", "name": "Programmes neufs par ville" },
"market": { "id": "…", "code": "fr-FR", "label": "France" },
"response": "Texte complet de la réponse du moteur",
"sources": ["https://exemple.com/page"],
"sentiment": "NEUTRAL",
"errorCode": null,
"citations": [
{ "id": "…", "excerpt": "…", "confidence": 0.9, "sentiment": "NEUTRAL" }
]
}
]
},
"warnings": [
"7 of the 175 answers failed, so this audit is partial: the score only covers the answers that came back. Each failed answer carries an errorCode."
]
}
  • currentProgress : avancement de 0 à 100. completedAt : null tant que l'audit n'est ni COMPLETED ni FAILED.
  • queries[].cited : la marque est-elle citée dans cette réponse, position son rang quand elle l'est. topic et market sont ceux du prompt. sources : les URL citées par le moteur. citations : les extraits où la marque apparaît, avec une confidence entre 0 et 1.
  • Réponses en échec : un appel au moteur qui a échoué donne un response qui commence par [ERROR] et un errorCode (par exemple PROVIDER_ERROR, ou DATAFORSEO_40101 pour Google AIO, UNKNOWN sur les anciens audits qui n'enregistraient pas le code). Ces réponses ne comptent pas dans le score. partial vaut true dès qu'il y en a une, failedAnswerCount dit combien, warnings le répète. analytics compte encore toutes les lignes, échecs compris.
  • promptsConfigured, promptsRun et warnings disent aussi quand des prompts ont été laissés de côté faute de budget.
  • 404 si la marque ou l'audit n'existe pas dans votre organisation.

Les audits COMPLETED sont mis en cache 5 minutes côté client (Cache-Control: private), les autres ne le sont pas : relisez-les librement pour suivre l'avancement.


Prompts →