list_audits

Cosa fa questo strumento

list_audits restituisce gli audit dell’utente, dal più recente, deduplicati per URL. È la directory di tutto ciò che run_audit ha prodotto per questo account.

• Restituisce un array piatto di elementi { audit_id, url, status, total_score, created_at }.
• Deduplica per URL: solo l’audit più recente per URL viene incluso.
• limit è opzionale, default 24, massimo 100.
• NON include i finding, chiama get_audit con l’audit_id scelto per il dettaglio completo.

Perché è importante

list_audits è la superficie di scoperta. Senza, un agente non ha modo di trovare audit eseguiti precedentemente in una sessione, da un altro agente o dall’utente nella dashboard.

Workflow concreti:

• Un agente “dashboard summary” chiama list_audits e renderizza un riassunto di una riga per URL con punteggio e timestamp.
• Un watcher di regressioni chiama list_audits, prende i due audit più recenti per URL tra i run e fa deep-load (get_audit) solo di quelli il cui total_score è sceso rispetto a una baseline salvata.

Come usarlo

Chiama senza argomenti per ottenere i 24 audit più recenti di default, o passa un limit tra 1 e 100. La risposta è un singolo oggetto JSON il cui campo audits è l’array.

Schema di input

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

Esempio di schema di risposta

{
  "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:

Elenca i miei ultimi 10 audit MetricSpot e ordinali per punteggio crescente così posso correggere prima gli URL peggiori.

Cursor

.cursor/mcp.json:

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

Prompt:

Usa list_audits per trovare ogni audit di example.com e dimmi quale pagina ha il punteggio totale peggiore.

Python (filtra e scegli il peggiore)

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 grezzo)

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

Errori comuni

Codice	Quando	Azione
UNAUTHORIZED (401)	Bearer token mancante o non valido	Genera una chiave su https://app.metricspot.com/settings/api-keys
INVALID_URL (400)	limit fuori dal range 1-100	Passa un intero in range, o omettilo
UPSTREAM_FAILED (5xx)	Errore del backend dell’app	Riprova con backoff

Domande frequenti

Perché gli URL duplicati vengono collassati?

La lista è pensata perché gli agenti scoprano il lavoro, non per scorrere la cronologia di audit. La maggior parte degli utenti si interessa a “qual è lo stato più recente di /pricing”, non a “mostrami ogni volta che ho auditato /pricing questo mese”. Per vedere ogni run precedente di un URL, usa la dashboard su app.metricspot.com/audits.

Posso paginare oltre 100?

Non in v1. limit è limitato a 100 per mantenere le risposte dentro le finestre di contesto degli agenti. Se ti serve un export completo, usa l’export CSV della dashboard (piano Pro) o direttamente la API dell’app sottostante.

Gli audit anonimi vengono mai restituiti?

No. Gli audit anonimi non sono persistiti su alcun account, quindi list_audits restituisce solo gli audit creati da chiamate run_audit autenticate legate al proprietario del token API.