GET /api/audits

Ce que fait cet endpoint

GET /api/audits renvoie les audits les plus récents du compte authentifié, dédupliqués par URL. Si vous avez audité la même URL dix fois, vous obtenez une ligne : la plus récente. La liste est ordonnée par la position d’affichage enregistrée par l’utilisateur (définie dans le tableau de bord) puis par created_at décroissant.

• Dédupliquée par URL : une ligne par URL unique.
• Ordonnée par display_position ASC NULLS LAST, created_at DESC.
• Renvoie jusqu’à 100 lignes par défaut. Pas de paramètres limit ou offset en v1 ; le tableau de bord récupère la même forme.
• Peu coûteux et idempotent : pas de coût plan, pas de PSI, pas d’appel crawler.

Pourquoi c’est important

C’est l’endpoint que touchent en premier un tableau de bord, un digest hebdomadaire ou un dashboard CI. Il donne chaque URL qui intéresse le compte avec son score le plus récent, prête à être liée à GET /api/audits/:id pour l’enveloppe complète ou à POST /api/audits pour relancer.

Workflows concrets :

• Un zap hebdomadaire appelle GET /api/audits, calcule les deltas par rapport au snapshot précédent dans Airtable et poste un message Slack pour chaque URL ayant perdu plus de 5 points.
• Un dashboard CI interne poll chaque minute et affiche une grille de statut classée par display_position, plaçant les pages les plus critiques en haut.

Comment l’utiliser

Auth Bearer obligatoire. Pas de paramètres de query.

Requête

GET /api/audits HTTP/1.1
Host: app.metricspot.com
Authorization: Bearer ms_live_xxxxxxxxxxxxxxxxxxxxxxxx

curl

curl https://app.metricspot.com/api/audits \
  -H "authorization: Bearer ms_live_xxxxxxxxxxxxxxxxxxxxxxxx"

Node fetch

const res = await fetch("https://app.metricspot.com/api/audits", {
  headers: { authorization: "Bearer ms_live_xxxxxxxxxxxxxxxxxxxxxxxx" },
});
const { audits } = await res.json();
for (const a of audits) {
  console.log(a.score, a.url);
}

Python httpx

import httpx

r = httpx.get(
    "https://app.metricspot.com/api/audits",
    headers={"authorization": "Bearer ms_live_xxxxxxxxxxxxxxxxxxxxxxxx"},
    timeout=30.0,
)
for a in r.json()["audits"]:
    print(f"{a['score'] or '..'} {a['url']} ({a['status']})")

Réponse

200 OK :

{
  "audits": [
    {
      "id": 12345,
      "domain": "example.com",
      "url": "https://example.com",
      "status": "completed",
      "score": 78,
      "created_at": "2026-05-14T10:18:04.000Z",
      "completed_at": "2026-05-14T10:18:24.000Z",
      "display_position": 0
    },
    {
      "id": 12321,
      "domain": "example.com",
      "url": "https://example.com/pricing",
      "status": "completed",
      "score": 71,
      "created_at": "2026-05-13T09:02:11.000Z",
      "completed_at": "2026-05-13T09:02:34.000Z",
      "display_position": 1
    }
  ]
}

Champs par ligne :

• id : id entier d’audit, utilisé dans les appels suivants.
• domain : hostname.
• url : URL complète auditée.
• status : un parmi queued, running, completed, failed.
• score : entier 0 à 100, ou null pendant la file ou l’exécution.
• created_at : horodatage ISO 8601.
• completed_at : horodatage ISO 8601, ou null si pas encore fini.
• display_position : rang entier fixé dans le tableau de bord par glisser-déposer, ou null si l’utilisateur n’a pas réordonné. L’endpoint trie d’abord par ce champ.

L’endpoint renvoie toujours {"audits": [...]}. Pas d’enveloppe de pagination ; le plafond est de 100 lignes. Utilisez POST /api/audits puis GET /api/audits/:id pour les détails complets par audit.

Enveloppe d’erreur

{ "error": "Unauthorized" }

Erreurs courantes

Code	Quand	Action
UNAUTHORIZED (401)	Bearer manquant ou invalide	Créez une clé sur app.metricspot.com/settings/api-keys
UPSTREAM_FAILED (5xx)	Aléa de base de données	Réessayez une fois avec backoff

L’endpoint ne renvoie jamais 404 ni 429 : c’est une liste de vos propres ressources sans rate limit au-delà du plan.

Questions fréquentes

Pourquoi la liste est-elle dédupliquée par URL ?

Le tableau de bord montre une carte par URL : réauditer la même URL remplace le score de la carte précédente. L’API reflète cette vue exactement pour qu’une UI tierce affiche la même liste sans réimplémenter la déduplication.

Comment obtenir chaque audit (y compris les anciens runs de la même URL) ?

Utilisez l’endpoint d’historique par URL exposé dans le détail de chaque audit. La liste est volontairement “le plus récent par URL” car c’est ce qu’il faut aux dashboards et digests. Une révision future pourra exposer un historique plat non paginé.

display_position est-il modifiable par API ?

Oui, indirectement : le glisser-déposer du tableau de bord mappe sur un endpoint de réordonnancement séparé qui prend un tableau d’URL dans le nouvel ordre. La liste lit les positions enregistrées ; elle ne les écrit pas.

Cela consomme-t-il du quota ?

Non. L’endpoint de listing n’est pas comptabilisé. Seul POST /api/audits (et seulement en cas de succès) décrémente le compteur mensuel.