get_audit

What this tool does

get_audit returns the full result of a previously-run audit by its audit_id. It is the polling target for run_audit and the canonical way to read every finding for a given URL.

• Returns the same McpAuditResponse envelope as run_audit, but with findings populated once the audit completes.
• Surfaces module scores (0-100) across all 11 audit modules, plus the aggregate total_score.
• Includes every finding with module, rule_id, passed, severity, title, optional recommendation, and a docs_url.
• Returns status reflecting upstream state: queued, running, complete, or failed.
• Provides a report_url deep-link to the HTML report on app.metricspot.com.

Why it matters

get_audit is the read side of the MCP server. Agents call it to poll a queued run, to re-read findings from a prior audit, or to compare two audits of the same URL over time.

Concrete workflows:

• A PR-comment bot calls get_audit for the previous audit on a URL, diffs total_score against the new one, and only escalates when the regression crosses a threshold.
• A “fix one finding at a time” agent loops through findings filtered by severity: critical, opens an issue per failing rule, and links the docs_url for context.

How to use it

Pass the audit_id returned by run_audit (or by list_audits). The same id can be re-queried repeatedly; results are cached server-side and cheap to read.

Input schema

{
  "type": "object",
  "properties": {
    "audit_id": { "type": "string", "minLength": 1 }
  },
  "required": ["audit_id"]
}

Response schema sample

{
  "audit_id": "aud_01HZ8X9YP7K3T2N6Q5",
  "url": "https://example.com",
  "status": "complete",
  "total_score": 82,
  "module_scores": {
    "technical": 95,
    "onpage": 76,
    "performance": 71,
    "ai": 84,
    "modern_seo": 80,
    "social": 65,
    "accessibility": 90,
    "privacy": 78,
    "readability": 85,
    "tech_stack": 100
  },
  "findings": [
    {
      "module": "technical",
      "rule_id": "technical.https",
      "passed": true,
      "severity": "critical",
      "title": "Site is served over HTTPS",
      "docs_url": "https://metricspot.com/docs/technical-https/"
    },
    {
      "module": "ai",
      "rule_id": "ai.llms_txt",
      "passed": false,
      "severity": "minor",
      "title": "No llms.txt published",
      "recommendation": "Add an llms.txt to /.well-known/ listing canonical docs URLs for LLM crawlers.",
      "docs_url": "https://metricspot.com/docs/llms-txt/"
    }
  ],
  "report_url": "https://app.metricspot.com/audits/aud_01HZ8X9YP7K3T2N6Q5",
  "created_at": "2026-05-13T10:18:04.000Z"
}

Claude Code

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

Prompt:

Fetch MetricSpot audit aud_01HZ8X9YP7K3T2N6Q5 and list every failed finding grouped by module, sorted by severity.

Cursor

.cursor/mcp.json:

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

Prompt:

Pull the last audit for this URL from MetricSpot and rewrite the page’s title to fix any failing on-page rules.

Python (poll until complete)

import httpx, time, json

HEADERS = {
    "content-type": "application/json",
    "accept": "application/json, text/event-stream",
    "authorization": "Bearer ms_live_xxxxxxxxxxxxxxxxxxxxxxxx",
}

def get_audit(audit_id):
    r = httpx.post("https://mcp.metricspot.com/mcp", headers=HEADERS, json={
        "jsonrpc": "2.0", "id": 1, "method": "tools/call",
        "params": {"name": "get_audit", "arguments": {"audit_id": audit_id}},
    }, timeout=60.0)
    return json.loads(r.json()["result"]["content"][0]["text"])

while True:
    audit = get_audit("aud_01HZ8X9YP7K3T2N6Q5")
    if audit["status"] in ("complete", "failed"):
        break
    time.sleep(3)

print("score:", audit["total_score"])
for f in audit["findings"]:
    if not f["passed"] and f["severity"] in ("critical", "major"):
        print(f["severity"], f["rule_id"], "-", f["title"])

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: "get_audit",
      arguments: { audit_id: "aud_01HZ8X9YP7K3T2N6Q5" },
    },
  }),
});
const audit = JSON.parse((await res.json()).result.content[0].text);
console.log(audit.status, audit.total_score);

Common errors

Code	When	Action
UNAUTHORIZED (401)	Missing or invalid Bearer token	Issue a key at https://app.metricspot.com/settings/api-keys
AUDIT_NOT_FOUND (404)	audit_id doesn’t belong to this account	Call list_audits for valid ids
FORBIDDEN (403)	Token lacks read scope	Reissue the key with the default scope
UPSTREAM_FAILED (5xx)	App backend error	Retry; retryable: true is set on transient failures

Frequently asked questions

How often should I poll a queued audit?

Every 3-5 seconds is the sweet spot. Most audits complete in 10-30 s, so 6-10 polls per audit is typical. There is no per-call cost beyond network. Back off if status stays queued for more than 90 s.

Can I fetch an audit that someone else ran?

No. The audit lookup is scoped to the API key’s owner. Calling get_audit with another user’s audit_id returns AUDIT_NOT_FOUND rather than leaking that the audit exists. Anonymous audits (id "anonymous") cannot be fetched at all.

Does the response include findings for rules that passed?

Yes. Every rule the engine evaluated is in findings, with passed: true or passed: false. Filter client-side to surface only failures, or to compute pass rates per module.