GET /api/audits/:id

Qué hace este endpoint

GET /api/audits/:id devuelve el envoltorio completo de una auditoría que tu cuenta posee: puntuaciones, desglose por módulo y cada regla evaluada. Es el endpoint que haces polling tras encolar con POST /api/audits.

• Idempotente y cacheable en cliente: los findings de una auditoría no cambian una vez status === "completed".
• Incluye plan (plan efectivo del usuario) y cooldown (cuándo se permite la próxima auditoría sobre la misma URL), que el panel usa para pintar botones de acción.
• Devuelve 404 si el id no existe, 403 si la auditoría pertenece a otra cuenta, 401 si el Bearer falta o es inválido.

Por qué importa

GET /api/audits/:id es la lectura de cualquier auditoría que encolaste. Es la llamada que pones en un bucle de polling de 3-5 segundos tras POST /api/audits y también la que haces más tarde cuando un agente quiere revisar los findings sin relanzarla.

Workflows concretos:

• Un bot de auditoría sobre PR hace polling cada 3 segundos hasta que status es completed, luego ordena los findings por severity y publica los tres peores en el PR.
• Un agente revisor de contenido recibe el id por webhook y saca los findings para redactar una lista de arreglos ordenada por módulo.

Cómo usarlo

El id es el entero devuelto por POST /api/audits. Auth Bearer obligatoria.

Petición

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"])

Respuesta

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" }
}

Campos:

• audit.status: uno de queued, running, completed, failed. Los findings solo son estables con completed.
• audit.score: entero 0 a 100, o null mientras está en cola o ejecutándose.
• audit.raw.module_scores: puntuación por módulo 0 a 100. Los módulos no aplicables devuelven null.
• audit.perf_status: ready cuando PageSpeed Insights responde; pending mientras está en vuelo.
• audit.error_message: poblado solo cuando status === "failed".
• findings[]: cada regla evaluada, incluidas las que pasan. Filtra por passed: false para quedarte solo con los fallos.
• findings[].severity: info, minor, major, critical. Ordena descendente para la lista de arreglos más útil.
• findings[].data: datos extra de la regla (p. ej. tamaños en píxeles, número de tags ausentes).
• plan: plan efectivo del usuario: free, starter o pro.
• cooldown.ready_at: timestamp ISO de la próxima auditoría permitida para esta URL.

Envoltorio de error

{ "error": "Not found" }

Errores comunes

Código	Cuándo	Acción
UNAUTHORIZED (401)	Bearer ausente o inválido	Crea una clave en app.metricspot.com/settings/api-keys
FORBIDDEN (403)	La auditoría pertenece a otra cuenta	Usa la clave de la cuenta propietaria, o llama a GET /api/audits
AUDIT_NOT_FOUND (404)	El :id no existe	Llama a GET /api/audits y usa un id real
INVALID_URL (400)	:id no es un entero positivo	Pasa un id entero

Preguntas frecuentes

¿Con qué frecuencia debo hacer polling?

3 a 5 segundos es el punto dulce. Más rápido desperdicia llamadas; más lento retrasa el comentario o la notificación. La mayoría de auditorías termina dentro de los 30 primeros segundos; rinde el bucle a los 90 segundos y muestra el estado “todavía en curso” al usuario.

¿Los findings vienen en un orden útil?

Vienen en orden de inserción (id ascendente), que refleja cómo corre la tubería los módulos. Para una lista de arreglos para humanos, ordena en cliente por severity (critical > major > minor > info) y luego por módulo.

¿Qué pasa si consulto una auditoría mientras corre?

Obtendrás status: "queued" o status: "running" con findings vacío y score: null. Los demás campos (id, domain, url, created_at) son estables desde la primera respuesta.

¿Consume cupo del plan?

No. Solo POST /api/audits (y solo cuando termina con éxito) decrementa el contador mensual. GET /api/audits/:id no consume.