# Audits GEO

> Endpoints API pour lister, lancer et lire les audits GEO, avec les réponses des moteurs IA question par question.

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](./authentication)). Lancer un audit demande en plus une clé avec le scope `write`.

:::info 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`](./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) :

```json
{
  "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) :**

```json
{
  "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) :**

```json
{
  "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 :**

```json
{
  "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 →](./suggestions)**