GET /api/audits/:id - Docs de MetricSpot

Què fa aquest endpoint

GET /api/audits/:id retorna el sobre complet d’una auditoria que el teu compte té en propietat: puntuacions, desglossament per mòdul i totes les regles avaluades. Aquest és l’endpoint sobre el qual fer poll després d’encuar amb POST /api/audits.

Idempotent i cacheable al client: els findings d’una auditoria no canvien mai un cop status === "completed".
Inclou plan (el pla efectiu actual de l’usuari) i cooldown (quan es permet la propera auditoria de la mateixa URL), que el dashboard utilitza per renderitzar els botons d’acció.
Retorna 404 si l’id no existeix, 403 si l’auditoria pertany a un altre compte i 401 si el token Bearer és absent o invàlid.

Per què importa

GET /api/audits/:id és la lectura per a qualsevol auditoria que has encuat. És la crida que poses en un bucle de poll de 3 a 5 segons després de POST /api/audits, i és la crida que fas més tard quan un agent vol revisar findings sense reexecutar l’auditoria.

Fluxos concrets:

Un bot d’auditoria a les PR fa poll cada 3 segons fins que status és completed, ordena els findings per severity i publica els tres pitjors a la PR.
Un agent revisor de contingut rep l’id de l’auditoria per webhook i obté els findings per redactar una llista de correccions ordenada per mòdul.

Com utilitzar-lo

L’id és l’enter retornat per POST /api/audits. L’autenticació Bearer és obligatòria.

Petició

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

curl

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

Node fetch

const res = await fetch("https://app.metricspot.com/api/audits/12345", {
  headers: { authorization: "Bearer ms_live_xxxxxxxxxxxxxxxxxxxxxxxx" },
});
const data = await res.json();
console.log(data.audit.status, data.audit.score);
console.log(`${data.findings.length} findings`);

Python httpx

import httpx

r = httpx.get(
    "https://app.metricspot.com/api/audits/12345",
    headers={"authorization": "Bearer ms_live_xxxxxxxxxxxxxxxxxxxxxxxx"},
    timeout=30.0,
)
data = r.json()
for f in data["findings"]:
    if not f["passed"] and f["severity"] in ("major", "critical"):
        print(f["severity"], f["rule_id"], f["title"])

Resposta

200 OK:

{
  "audit": {
    "id": 12345,
    "user_id": 42,
    "domain": "example.com",
    "url": "https://example.com",
    "status": "completed",
    "score": 78,
    "audit_version": 7,
    "raw": {
      "module_scores": {
        "technical": 92,
        "onpage": 71,
        "performance": 84,
        "ai": 65,
        "modern_seo": 80,
        "social": 88,
        "accessibility": 74,
        "privacy": 82,
        "readability": 70,
        "tech_stack": 100,
        "organic_traffic": 100
      }
    },
    "perf_status": "ready",
    "error_message": null,
    "started_at": "2026-05-14T10:18:05.000Z",
    "completed_at": "2026-05-14T10:18:24.000Z",
    "created_at": "2026-05-14T10:18:04.000Z"
  },
  "findings": [
    {
      "id": 9001,
      "module": "onpage",
      "rule_id": "onpage.meta-description",
      "severity": "major",
      "passed": false,
      "title": "Missing meta description",
      "recommendation": "Add a 140-160 character meta description summarizing the page.",
      "data": {}
    }
  ],
  "plan": "starter",
  "cooldown": { "ready_at": "2026-05-15T10:18:04.000Z" }
}

Camps:

audit.status: un de queued, running, completed, failed. Els findings només són estables un cop completed.
audit.score: enter de 0 a 100, o null mentre està encuada o en execució.
audit.raw.module_scores: puntuació per mòdul de 0 a 100. Els mòduls que no eren aplicables retornen null.
audit.perf_status: ready quan PageSpeed Insights respon; pending mentre PSI encara està en vol.
audit.error_message: només omplert quan status === "failed".
findings[]: totes les regles avaluades, incloses les que han passat. Filtra per passed: false per quedar-te només amb els errors.
findings[].severity: info, minor, major, critical. Ordena descendent per severitat per obtenir la llista de correccions més útil.
findings[].data: dades extra específiques de la regla (p. ex. mides en píxels mesurades, recompte de tags absents).
plan: el pla efectiu de l’usuari: free, starter o pro.
cooldown.ready_at: timestamp ISO de la propera auditoria permesa per a aquesta URL.

Sobre d’error

{ "error": "Not found" }

Errors habituals

Codi	Quan	Acció
`UNAUTHORIZED` (401)	Token Bearer absent o invàlid	Emet una clau a `app.metricspot.com/settings/api-keys`
`FORBIDDEN` (403)	L’auditoria pertany a un altre compte	Utilitza una clau del compte propietari, o crida `GET /api/audits` per llistar les teves
`AUDIT_NOT_FOUND` (404)	`:id` no existeix	Crida `GET /api/audits` i utilitza un id real
`INVALID_URL` (400)	`:id` no és un enter positiu	Passa un id enter

Preguntes freqüents

Amb quina freqüència he de fer poll?

3 a 5 segons és el punt dolç. Més ràpid malgasta round trips; més lent retarda el comentari o la notificació downstream. La majoria d’auditories acaben en els primers 30 segons; aborta als 90 segons i mostra l’estat encara en execució a l’usuari.

Els findings estan ordenats de manera útil?

Es retornen en ordre d’inserció (per id ascendent), que reflecteix com la cadena d’auditoria executa els mòduls. Per a una llista de correccions de cara a una persona, ordena al client per severity (critical > major > minor > info), i després per mòdul.

Què passa si obtinc una auditoria mentre encara està en execució?

Reps status: "queued" o status: "running" amb un array findings buit i score: null. Els altres camps (id, domain, url, created_at) són estables des de la primera resposta.

Consumeix allocació del pla?

No. Només POST /api/audits (i només quan té èxit) decrementa el comptador mensual. GET /api/audits/:id no està comptabilitzat.