list_audits

Què fa aquesta eina

list_audits retorna les auditories de l’usuari, més recents primer, deduplicades per URL. És el directori de tot el que run_audit ha produït per a aquest compte.

• Retorna un array pla d’elements { audit_id, url, status, total_score, created_at }.
• Dedupliquen per URL: només s’inclou l’auditoria més recent per URL.
• limit és opcional, per defecte 24, màxim 100.
• NO inclou findings: crida get_audit amb l’audit_id triat per al detall complet.

Per què importa

list_audits és la superfície de discovery. Sense ella, un agent no té manera de trobar auditories executades abans en una sessió, per un altre agent o per l’usuari al dashboard.

Fluxos concrets:

• Un agent “resum de dashboard” crida list_audits i renderitza un resum d’una línia per URL amb puntuació i timestamp.
• Un vigilant de regressions crida list_audits, tria les dues auditories més recents per URL entre execucions, i només carrega en profunditat (get_audit) les que tenen total_score caigut respecte a una baseline desada.

Com utilitzar-la

Crida sense arguments per obtenir per defecte les 24 auditories més recents, o passa un limit entre 1 i 100. La resposta és un objecte JSON el camp audits del qual és l’array.

Esquema d’entrada

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

Mostra de l’esquema 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"

Prompt:

List my last 10 MetricSpot audits and sort them by score ascending so I can fix the worst URLs first.

Cursor

.cursor/mcp.json:

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

Prompt:

Use list_audits to find every audit for example.com and tell me which page has the worst total score.

Python (filtrar i triar el pitjor)

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 en cru)

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`);

Errors habituals

Codi	Quan	Acció
UNAUTHORIZED (401)	Token Bearer absent o invàlid	Emet una clau a https://app.metricspot.com/settings/api-keys
INVALID_URL (400)	limit fora de 1-100	Passa un enter dins del rang, o omet-lo
UPSTREAM_FAILED (5xx)	Error de backend de l’app	Reintenta amb backoff

Preguntes freqüents

Per què es col·lapsen les URLs duplicades?

La llista està pensada perquè els agents descobreixin feina, no per recórrer l’historial d’auditories. La majoria d’usuaris els importa “quin és l’estat actual de /pricing”, no “mostra’m cada cop que he auditat /pricing aquest mes”. Per veure totes les execucions prèvies d’una URL, utilitza el dashboard a app.metricspot.com/audits.

Puc paginar més enllà de 100?

A la v1 no. limit està limitat a 100 per mantenir les respostes dins la finestra de context dels agents. Si necessites una exportació completa, utilitza l’exportació CSV del dashboard (pla Pro) o l’API de l’app subjacent directament.

Es retornen mai auditories anònimes?

No. Les auditories anònimes no es persisteixen a cap compte, així que list_audits només retorna auditories creades per crides autenticades de run_audit lligades al propietari del token d’API.