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.
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"]
}
| Champ | Défaut | Description |
|---|---|---|
providers | les 5 moteurs de base, voir plus bas | Moteurs à 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 |
region | fr | Repli 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é |
model | aucun | Ancien champ, un seul modèle (par exemple gpt-4.1). Ignoré si providers est présent, 400 si le modèle est inconnu |
keywords | aucun | Accepté 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
providersnimodel, 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 danswarnings. Si mêmechatgptseul ne couvre pas tous les prompts, il tourne seul sur ceux qui tiennent etwarningsle 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 avecpromptsConfigured,promptsRunetwarnings.
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.
| Statut | Cas |
|---|---|
201 | Audit créé, ou audit déjà en cours renvoyé |
400 | providers 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é |
403 | Clé sans scope write, forfait sans accès API, ou code: "plan_required" : forfait sans audit manuel ou moteur hors forfait |
404 | Marque introuvable dans votre organisation |
429 | code: "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 |
500 | code: "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:nulltant que l'audit n'est niCOMPLETEDniFAILED.queries[].cited: la marque est-elle citée dans cette réponse,positionson rang quand elle l'est.topicetmarketsont ceux du prompt.sources: les URL citées par le moteur.citations: les extraits où la marque apparaît, avec uneconfidenceentre 0 et 1.- Réponses en échec : un appel au moteur qui a échoué donne un
responsequi commence par[ERROR]et unerrorCode(par exemplePROVIDER_ERROR, ouDATAFORSEO_40101pour Google AIO,UNKNOWNsur les anciens audits qui n'enregistraient pas le code). Ces réponses ne comptent pas dans le score.partialvauttruedès qu'il y en a une,failedAnswerCountdit combien,warningsle répète.analyticscompte encore toutes les lignes, échecs compris. promptsConfigured,promptsRunetwarningsdisent aussi quand des prompts ont été laissés de côté faute de budget.404si 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.