list_audits

Qué hace esta herramienta

list_audits devuelve las auditorías del usuario, de la más reciente a la más antigua, deduplicadas por URL. Es el directorio de todo lo que run_audit ha producido para esta cuenta.

• Devuelve un array plano de items { audit_id, url, status, total_score, created_at }.
• Deduplica por URL: solo se incluye la auditoría más reciente por URL.
• limit es opcional, por defecto 24, máximo 100.
• NO incluye hallazgos: llama a get_audit con el audit_id elegido para el detalle completo.

Por qué importa

list_audits es la superficie de descubrimiento. Sin ella, un agente no tiene forma de encontrar auditorías ejecutadas antes en la sesión, por otro agente o por el usuario en el panel.

Flujos concretos:

• Un agente de “resumen de panel” llama a list_audits y renderiza un resumen de una línea por URL con puntuación y timestamp.
• Un vigilante de regresiones llama a list_audits, escoge las dos auditorías más recientes por URL entre ejecuciones y solo carga en profundidad (get_audit) aquellas cuyo total_score haya caído frente a una línea base almacenada.

Cómo usarla

Llama sin argumentos para obtener las 24 auditorías más recientes por defecto, o pasa un limit entre 1 y 100. La respuesta es un único objeto JSON cuyo campo audits es el array.

Esquema de entrada

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

Ejemplo de esquema de respuesta

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

Pide:

Lista mis últimas 10 auditorías de MetricSpot y ordénalas por puntuación ascendente para que pueda corregir primero las peores URLs.

Cursor

.cursor/mcp.json:

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

Pide:

Usa list_audits para encontrar cada auditoría de example.com y dime qué página tiene la peor puntuación total.

Python (filtrar y elegir la peor)

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

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

Errores comunes

Código	Cuándo	Acción
UNAUTHORIZED (401)	Token Bearer ausente o inválido	Emite una clave en https://app.metricspot.com/settings/api-keys
INVALID_URL (400)	limit fuera del rango 1-100	Pasa un entero en rango, u omítelo
UPSTREAM_FAILED (5xx)	Error en el backend de la app	Reintenta con backoff

Preguntas frecuentes

¿Por qué se colapsan las URLs duplicadas?

La lista está pensada para que los agentes descubran trabajo, no para recorrer el historial de auditorías. A la mayoría de usuarios les importa “¿cuál es el estado más reciente de /pricing?”, no “muéstrame cada vez que audité /pricing este mes”. Para ver cada ejecución previa de una URL, usa el panel en app.metricspot.com/audits.

¿Puedo paginar más allá de 100?

No en v1. limit está limitado a 100 para mantener las respuestas dentro de las ventanas de contexto de los agentes. Si necesitas un export completo, usa la exportación CSV del panel (plan Pro) o la API de la app subyacente directamente.

¿Se devuelven alguna vez auditorías anónimas?

No. Las auditorías anónimas no se persisten en ninguna cuenta, así que list_audits solo devuelve auditorías creadas por llamadas autenticadas a run_audit asociadas al propietario del token API.