list_audits

O que esta ferramenta faz

list_audits devolve as auditorias do utilizador, da mais recente para a mais antiga, desduplicadas por URL. É o diretório de tudo o que run_audit produziu nesta conta.

• Devolve um array plano de itens { audit_id, url, status, total_score, created_at }.
• Desduplica por URL: apenas a auditoria mais recente por URL é incluída.
• limit é opcional, por defeito 24, máximo 100.
• NÃO inclui descobertas, chama get_audit com o audit_id escolhido para o detalhe completo.

Por que importa

list_audits é a superfície de descoberta. Sem ela, um agente não tem forma de encontrar auditorias que foram executadas antes na sessão, por outro agente, ou pelo utilizador no dashboard.

Fluxos concretos:

• Um agente “resumo do dashboard” chama list_audits e renderiza um resumo numa linha por URL com pontuação e timestamp.
• Um vigilante de regressões chama list_audits, escolhe as duas auditorias mais recentes por URL entre execuções, e só carrega em profundidade (get_audit) aquelas cujo total_score caiu face a uma baseline guardada.

Como usá-la

Chama sem argumentos para obter as 24 auditorias mais recentes por defeito, ou passa um limit entre 1 e 100. A resposta é um objeto JSON cujo campo audits é o array.

Schema de entrada

{
  "type": "object",
  "properties": {
    "limit": { "type": "integer", "minimum": 1, "maximum": 100, "default": 24 }
  }
}

Amostra do schema de resposta

{
  "audits": [
    {
      "audit_id": "aud_01HZ8X9YP7K3T2N6Q5",
      "url": "https://example.com",
      "status": "complete",
      "total_score": 82,
      "created_at": "2026-05-13T10:18:04.000Z"
    },
    {
      "audit_id": "aud_01HZ8W1B6F4Q8M3R7T",
      "url": "https://example.com/pricing",
      "status": "complete",
      "total_score": 74,
      "created_at": "2026-05-12T17:02:11.000Z"
    },
    {
      "audit_id": "aud_01HZ8V5J3K9N2P6S4D",
      "url": "https://example.com/blog/new-launch",
      "status": "queued",
      "total_score": null,
      "created_at": "2026-05-13T11:01:33.000Z"
    }
  ]
}

Claude Code

claude mcp add --transport http metricspot https://mcp.metricspot.com/mcp \
  --header "Authorization: Bearer ms_live_xxxxxxxxxxxxxxxxxxxxxxxx"

Pede:

Lista as minhas últimas 10 auditorias MetricSpot e ordena-as por pontuação ascendente para eu corrigir primeiro os piores URLs.

Cursor

.cursor/mcp.json:

{
  "mcpServers": {
    "metricspot": {
      "url": "https://mcp.metricspot.com/mcp",
      "headers": {
        "Authorization": "Bearer ms_live_xxxxxxxxxxxxxxxxxxxxxxxx"
      }
    }
  }
}

Pede:

Usa list_audits para encontrar todas as auditorias de example.com e diz-me que página tem a pior pontuação total.

Python (filtrar e escolher a pior)

import httpx, json

r = httpx.post("https://mcp.metricspot.com/mcp", headers={
    "content-type": "application/json",
    "accept": "application/json, text/event-stream",
    "authorization": "Bearer ms_live_xxxxxxxxxxxxxxxxxxxxxxxx",
}, json={
    "jsonrpc": "2.0", "id": 1, "method": "tools/call",
    "params": {"name": "list_audits", "arguments": {"limit": 50}},
}, timeout=30.0)

audits = json.loads(r.json()["result"]["content"][0]["text"])["audits"]
ranked = sorted(
    (a for a in audits if a["status"] == "complete" and a["total_score"] is not None),
    key=lambda a: a["total_score"],
)
print("worst:", ranked[0]["url"], ranked[0]["total_score"])

Node / TypeScript (HTTP direto)

const res = await fetch("https://mcp.metricspot.com/mcp", {
  method: "POST",
  headers: {
    "content-type": "application/json",
    accept: "application/json, text/event-stream",
    authorization: "Bearer ms_live_xxxxxxxxxxxxxxxxxxxxxxxx",
  },
  body: JSON.stringify({
    jsonrpc: "2.0",
    id: 1,
    method: "tools/call",
    params: { name: "list_audits", arguments: { limit: 25 } },
  }),
});
const { audits } = JSON.parse((await res.json()).result.content[0].text);
console.log(`${audits.length} audits`);

Erros comuns

Código	Quando	Ação
UNAUTHORIZED (401)	Token Bearer em falta ou inválido	Emite uma chave em https://app.metricspot.com/settings/api-keys
INVALID_URL (400)	limit fora de 1-100	Passa um inteiro no intervalo, ou omite
UPSTREAM_FAILED (5xx)	Erro no backend da app	Tenta de novo com backoff

Perguntas frequentes

Porque é que URLs duplicados são colapsados?

A lista serve para os agentes descobrirem trabalho, não para percorrerem o histórico de auditorias. A maior parte dos utilizadores interessa-se por “qual é o estado mais recente de /pricing”, não por “mostra-me todas as vezes que auditei /pricing este mês”. Para ver cada execução anterior de um URL, usa o dashboard em app.metricspot.com/audits.

Posso paginar para lá de 100?

Não na v1. limit está limitado a 100 para manter as respostas dentro das janelas de contexto dos agentes. Se precisares de uma exportação completa, usa a exportação CSV do dashboard (plano Pro) ou a API subjacente da app diretamente.

As auditorias anónimas são alguma vez devolvidas?

Não. As auditorias anónimas não são persistidas a nenhuma conta, por isso list_audits apenas devolve auditorias criadas por chamadas run_audit autenticadas associadas ao dono do token API.