list_audits

What this tool does

list_audits returns the user’s audits, most recent first, deduplicated by URL. It is the directory of everything run_audit has produced for this account.

• Returns a flat array of { audit_id, url, status, total_score, created_at } items.
• Deduplicates by URL: only the most recent audit per URL is included.
• limit is optional, defaults to 24, max 100.
• Does NOT include findings: call get_audit with the chosen audit_id for the full detail.

Why it matters

list_audits is the discovery surface. Without it, an agent has no way to find audits that were run earlier in a session, by another agent, or by the user in the dashboard.

Concrete workflows:

• A “dashboard summary” agent calls list_audits and renders a one-line summary per URL with score and timestamp.
• A regression watcher calls list_audits, picks the two most recent audits per URL across runs, and only deep-loads (get_audit) the ones whose total_score dropped versus a stored baseline.

How to use it

Call with no arguments to get the default 24 most-recent audits, or pass a limit between 1 and 100. The response is one JSON object whose audits field is the array.

Input schema

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

Response schema sample

{
  "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 (filter and pick worst)

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 (raw HTTP)

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

Common errors

Code	When	Action
UNAUTHORIZED (401)	Missing or invalid Bearer token	Issue a key at https://app.metricspot.com/settings/api-keys
INVALID_URL (400)	limit outside 1-100	Pass an integer in range, or omit
UPSTREAM_FAILED (5xx)	App backend error	Retry with backoff

Frequently asked questions

Why are duplicate URLs collapsed?

The list is meant for agents to discover work, not to walk audit history. Most users care about “what’s the latest state of /pricing”, not “show me every time I audited /pricing this month”. To see every prior run of a URL, use the dashboard at app.metricspot.com/audits.

Can I paginate past 100?

Not in v1. limit is capped at 100 to keep responses inside agent context windows. If you need a full export, use the dashboard CSV export (Pro plan) or the underlying app API directly.

Are anonymous audits ever returned?

No. Anonymous audits are not persisted to any account, so list_audits only returns audits created by authenticated run_audit calls keyed to the API token’s owner.