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 Pro ou Expert (voir Authentification). 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 du projet. Ils se créent dans le dashboard ou via les outils MCP create_prompts et import_prompts, pas via /keywords. Vérifiez qu'il y en a avant de lancer.

---

POST /projects/:id/audits

Lance un audit GEO. Scope write requis.

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

{
  "keywords": ["geo saas"],
  "model": "gpt-4.1",
  "region": "fr"
}

Champ	Défaut	Description
keywords	aucun	Mots-clés de contexte pour l'analyse du site. Ne remplace pas les prompts et ne les sélectionne pas. Sans valeur, le titre du site est utilisé
model	gpt-4.1	Modèle à interroger. Les modèles disponibles dépendent de votre forfait
region	fr	Langue/région de la simulation

Réponse (201 Created) :

{
  "data": {
    "auditId": "3f6c0d52-1b9e-4c5a-9a53-0c7f3d2a1e44",
    "jobId": "b2d1c7e0-5a41-4a6e-8f1d-6a0b9c3e7f10"
  }
}

Si un audit est déjà en cours sur le projet, aucun second audit n'est créé : la réponse est aussi un 201, avec l'auditId de l'audit en cours, jobId: null et reused: true.

Statut	Cas
201	Audit créé ou audit déjà en cours renvoyé
403	Clé sans scope write, ou forfait sans accès API
404	Projet introuvable dans votre organisation
500	Failed to start audit, y compris quand le quota d'audits du mois ou l'accès au modèle demandé est refusé

Chaque audit consomme du quota mensuel.

---

GET /projects/:id/audits

Liste les audits du projet, 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": 78,
      "status": "COMPLETED",
      "duration": 4500,
      "created_at": "2026-01-22T15:30:00Z",
      "completed_at": "2026-01-22T15:34:10Z",
      "technical_details": { "model": "gpt-4.1", "region": "fr" },
      "provider_scores": {},
      "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.

---

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": 78,
    "status": "COMPLETED",
    "currentProgress": 100,
    "duration": 4500,
    "technicalDetails": { "model": "gpt-4.1", "region": "fr" },
    "providerScores": {},
    "source": "manual",
    "isAutomatic": false,
    "createdAt": "2026-01-22T15:30:00Z",
    "completedAt": "2026-01-22T15:34:10Z",
    "project": { "id": "…", "name": "…", "url": "https://exemple.com" },
    "analytics": {
      "totalQueries": 12,
      "citedQueries": 5,
      "citationRate": 42,
      "totalCitations": 7,
      "avgConfidence": 81,
      "confidenceDistribution": { "high": 4, "medium": 2, "low": 1 },
      "providerBreakdown": [{ "provider": "CHATGPT", "cited": 5, "total": 12, "rate": 42 }]
    },
    "queries": [
      {
        "id": "…",
        "prompt": "Quel est le meilleur outil GEO ?",
        "response": "Texte complet de la réponse du moteur",
        "provider": "chatgpt",
        "cited": true,
        "sources": ["https://exemple.com/page"],
        "sentiment": "POSITIVE",
        "citations": [
          { "id": "…", "excerpt": "…", "confidence": 0.9, "sentiment": "POSITIVE" }
        ]
      }
    ]
  }
}

• 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. sources : les URL citées par le moteur. citations : les extraits où la marque apparaît, avec une confidence entre 0 et 1.
• 404 si le projet 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.

---

Suggestions IA →