GET /api/audits

O que este endpoint faz

GET /api/audits devolve as auditorias mais recentes da conta autenticada, deduplicadas por URL. Se você auditou o mesmo URL dez vezes, recebe uma linha de volta: a mais recente. A lista é ordenada pela posição de exibição guardada (definida no painel) e depois por created_at descendente.

• Deduplicado por URL: uma linha por URL único.
• Ordenado por display_position ASC NULLS LAST, created_at DESC.
• Devolve até 100 linhas por padrão. Sem parâmetros limit ou offset na v1; o painel busca a mesma forma.
• Barato e idempotente: sem custo de plano, sem PSI, sem chamada de crawler.

Por que importa

Este é o endpoint que um painel, digest semanal, ou painel de CI bate primeiro. Devolve cada URL com que a conta se preocupa com a sua pontuação mais recente, pronto para ligar a GET /api/audits/:id para o envelope completo ou a POST /api/audits para enfileirar uma nova execução.

Fluxos concretos:

• Um zap Zapier semanal chama GET /api/audits, compara pontuações com o snapshot da semana passada em Airtable, e posta uma mensagem Slack para cada URL que caiu mais de 5 pontos.
• Um painel CI interno faz polling no endpoint a cada minuto e renderiza uma grelha de estado pelo display_position para que as páginas mais importantes apareçam primeiro.

Como usar

Auth Bearer obrigatória. Sem parâmetros de query.

Requisição

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

Resposta

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

Campos por linha:

• id: id inteiro da auditoria, usado em chamadas de seguimento.
• domain: hostname.
• url: URL completo auditado.
• status: um de queued, running, completed, failed.
• score: inteiro 0 a 100, ou null enquanto enfileirada ou em execução.
• created_at: timestamp ISO 8601.
• completed_at: timestamp ISO 8601, ou null se não completou.
• display_position: rank inteiro definido no painel por drag-and-drop, ou null se o utilizador não reordenou. O endpoint ordena por isto primeiro.

O endpoint devolve sempre {"audits": [...]}. Não há envelope de paginação; o teto é de 100 linhas. Use POST /api/audits seguido por GET /api/audits/:id para detalhe completo por auditoria.

Envelope de erro

{ "error": "Unauthorized" }

Erros comuns

Código	Quando	Ação
UNAUTHORIZED (401)	Bearer ausente ou inválido	Gere uma chave em app.metricspot.com/settings/api-keys
UPSTREAM_FAILED (5xx)	Falha de base de dados	Tente novamente com backoff

O endpoint nunca devolve 404 ou 429: é uma lista dos seus próprios recursos sem rate limit além do seu plano.

Perguntas frequentes

Por que a lista é deduplicada por URL?

O painel mostra um cartão por URL: auditar o mesmo URL de novo substitui a pontuação do cartão anterior. A API espelha essa vista exatamente para que uma UI de terceiros possa renderizar a mesma lista sem reimplementar a deduplicação.

Como obtenho cada auditoria (incluindo execuções antigas do mesmo URL)?

Use o endpoint de histórico por URL exposto no detalhe da auditoria. O endpoint de lista é intencionalmente a vista “mais recente por URL” porque é isso que painéis e digests precisam. Uma revisão futura pode expor um histórico plano não-paginado.

display_position é editável via API?

Sim, indiretamente: o drag-and-drop do painel mapeia para um endpoint de reorder separado que recebe um array de URLs na nova ordem. O endpoint de lista lê as posições guardadas; não escreve.

Isto conta contra quota do plano?

Não. O endpoint de lista é não-medido. Só POST /api/audits (e apenas em sucesso) decrementa o contador mensal.