GET /api/audits/:id

O que este endpoint faz

GET /api/audits/:id devolve o envelope completo de uma auditoria que a sua conta possui: pontuações, divisão por módulo e cada regra avaliada. Este é o endpoint para fazer polling depois de enfileirar com POST /api/audits.

• Idempotente e cacheável do lado cliente: os findings de uma auditoria não mudam mais quando status === "completed".
• Inclui plan (plano efetivo atual do utilizador) e cooldown (quando a próxima auditoria no mesmo URL é permitida), que o painel usa para renderizar os botões.
• Devolve 404 se o id não existir, 403 se a auditoria pertencer a outra conta, 401 se o token Bearer estiver ausente ou inválido.

Por que importa

GET /api/audits/:id é a releitura de qualquer auditoria que você enfileirou. É a chamada que você coloca num loop de polling de 3-5 segundos depois de POST /api/audits, e é a chamada que você faz mais tarde quando um agente quer rever findings sem rodar a auditoria de novo.

Fluxos concretos:

• Um bot audit-on-PR faz polling a cada 3 segundos até status ser completed, depois ordena os findings por severity e posta os três piores no PR.
• Um agente revisor de conteúdo recebe o id da auditoria por webhook e puxa os findings para rascunhar uma lista de correções ordenada por módulo.

Como usar

O id é o inteiro devolvido por POST /api/audits. Auth Bearer é obrigatória.

Requisição

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

Campos:

• audit.status: um de queued, running, completed, failed. Findings só são estáveis quando completed.
• audit.score: inteiro 0 a 100, ou null enquanto enfileirada ou em execução.
• audit.raw.module_scores: pontuação por módulo 0 a 100. Módulos não aplicáveis devolvem null.
• audit.perf_status: ready quando o PageSpeed Insights devolve; pending enquanto o PSI ainda está em voo.
• audit.error_message: preenchido apenas quando status === "failed".
• findings[]: cada regra avaliada, incluindo as que passaram. Filtre por passed: false para obter apenas as falhas.
• findings[].severity: info, minor, major, critical. Ordene desc por severity para a lista de correções mais útil.
• findings[].data: dados extra específicos da regra (ex: tamanhos de pixel medidos, contagem de tags em falta).
• plan: plano efetivo do utilizador: free, starter ou pro.
• cooldown.ready_at: timestamp ISO da próxima auditoria permitida para este URL.

Envelope de erro

{ "error": "Not found" }

Erros comuns

Código	Quando	Ação
UNAUTHORIZED (401)	Bearer ausente ou inválido	Gere uma chave em app.metricspot.com/settings/api-keys
FORBIDDEN (403)	Auditoria pertence a outra conta	Use a chave da conta proprietária, ou chame GET /api/audits para listar as suas
AUDIT_NOT_FOUND (404)	:id não existe	Chame GET /api/audits e use um id real
INVALID_URL (400)	:id não é um inteiro positivo	Passe um id inteiro

Perguntas frequentes

Com que frequência devo fazer polling?

3 a 5 segundos é o ponto ideal. Mais rápido desperdiça round trips; mais lento atrasa o seu comentário ou notificação downstream. A maioria das auditorias completa dentro dos primeiros 30 segundos; faça bail aos 90 segundos e exponha o estado ainda-em-execução ao utilizador.

Os findings vêm numa ordem útil?

São devolvidos na ordem de inserção (por id ascendente), o que espelha como o pipeline de auditoria roda os módulos. Para uma lista de correções voltada ao humano, ordene do lado cliente por severity (critical > major > minor > info), depois por módulo.

O que acontece se eu buscar uma auditoria enquanto ainda está a rodar?

Vai receber status: "queued" ou status: "running" com um array findings vazio e score: null. Os outros campos (id, domain, url, created_at) são estáveis desde a primeira resposta.

Isto consome quota do plano?

Não. Só POST /api/audits (e apenas quando bem-sucedido) decrementa o contador mensal. GET /api/audits/:id é não-medido.