GET /api/audits/:id

Was dieser Endpunkt macht

GET /api/audits/:id liefert den vollen Audit-Envelope für einen Audit, den dein Konto besitzt: Scores, Modulaufschlüsselung und jede evaluierte Regel. Das ist der Endpunkt, den du nach POST /api/audits pollst.

• Idempotent und clientseitig cachebar: die Findings eines Audits ändern sich nicht, sobald status === "completed".
• Enthält plan (effektiver Plan des Nutzers) und cooldown (wann der nächste Audit auf derselben URL erlaubt ist), die das Dashboard zur Buttondarstellung nutzt.
• Liefert 404, wenn die id nicht existiert, 403 wenn der Audit zu einem anderen Konto gehört, 401 wenn das Bearer-Token fehlt oder ungültig ist.

Warum das wichtig ist

GET /api/audits/:id ist der Readback für jeden eingereihten Audit. Es ist der Aufruf, den du nach POST /api/audits in eine 3-5 Sekunden-Pollingschleife steckst, und der Aufruf, den du später machst, wenn ein Agent Findings erneut prüfen will, ohne den Audit neu zu laufen.

Konkrete Workflows:

• Ein Audit-on-PR-Bot pollt alle 3 Sekunden bis status completed ist, sortiert dann die findings nach severity und postet die drei schlimmsten in den PR.
• Ein Content-Review-Agent erhält die Audit-id per Webhook und holt die Findings, um eine modulgeordnete Fix-Liste zu entwerfen.

Wie du ihn nutzt

Die id ist die von POST /api/audits zurückgegebene ganze Zahl. Bearer-Auth Pflicht.

Request

GET /api/audits/12345 HTTP/1.1
Host: app.metricspot.com
Authorization: Bearer ms_live_xxxxxxxxxxxxxxxxxxxxxxxx

curl

curl https://app.metricspot.com/api/audits/12345 \
  -H "authorization: Bearer ms_live_xxxxxxxxxxxxxxxxxxxxxxxx"

Node fetch

const res = await fetch("https://app.metricspot.com/api/audits/12345", {
  headers: { authorization: "Bearer ms_live_xxxxxxxxxxxxxxxxxxxxxxxx" },
});
const data = await res.json();
console.log(data.audit.status, data.audit.score);
console.log(`${data.findings.length} findings`);

Python httpx

import httpx

r = httpx.get(
    "https://app.metricspot.com/api/audits/12345",
    headers={"authorization": "Bearer ms_live_xxxxxxxxxxxxxxxxxxxxxxxx"},
    timeout=30.0,
)
data = r.json()
for f in data["findings"]:
    if not f["passed"] and f["severity"] in ("major", "critical"):
        print(f["severity"], f["rule_id"], f["title"])

Antwort

200 OK:

{
  "audit": {
    "id": 12345,
    "user_id": 42,
    "domain": "example.com",
    "url": "https://example.com",
    "status": "completed",
    "score": 78,
    "audit_version": 7,
    "raw": {
      "module_scores": {
        "technical": 92,
        "onpage": 71,
        "performance": 84,
        "ai": 65,
        "modern_seo": 80,
        "social": 88,
        "accessibility": 74,
        "privacy": 82,
        "readability": 70,
        "tech_stack": 100,
        "organic_traffic": 100
      }
    },
    "perf_status": "ready",
    "error_message": null,
    "started_at": "2026-05-14T10:18:05.000Z",
    "completed_at": "2026-05-14T10:18:24.000Z",
    "created_at": "2026-05-14T10:18:04.000Z"
  },
  "findings": [
    {
      "id": 9001,
      "module": "onpage",
      "rule_id": "onpage.meta-description",
      "severity": "major",
      "passed": false,
      "title": "Missing meta description",
      "recommendation": "Add a 140-160 character meta description summarizing the page.",
      "data": {}
    }
  ],
  "plan": "starter",
  "cooldown": { "ready_at": "2026-05-15T10:18:04.000Z" }
}

Felder:

• audit.status: einer aus queued, running, completed, failed. Findings sind nur bei completed stabil.
• audit.score: ganze Zahl 0 bis 100, oder null während Queue oder Run.
• audit.raw.module_scores: Score pro Modul 0 bis 100. Nicht-anwendbare Module liefern null.
• audit.perf_status: ready sobald PageSpeed Insights antwortet; pending solange PSI noch läuft.
• audit.error_message: nur gesetzt bei status === "failed".
• findings[]: jede evaluierte Regel, inklusive der bestandenen. Auf passed: false filtern für nur die Fehlschläge.
• findings[].severity: info, minor, major, critical. Absteigend sortieren für die nützlichste Fix-Liste.
• findings[].data: regelspezifische Zusatzdaten (z. B. gemessene Pixelgrößen, Anzahl fehlender Tags).
• plan: effektiver Plan des Nutzers: free, starter oder pro.
• cooldown.ready_at: ISO-Zeitstempel des nächsten erlaubten Audits für diese URL.

Fehler-Envelope

{ "error": "Not found" }

Häufige Fehler

Code	Wann	Aktion
UNAUTHORIZED (401)	Bearer-Token fehlt oder ist ungültig	Schlüssel erzeugen auf app.metricspot.com/settings/api-keys
FORBIDDEN (403)	Audit gehört einem anderen Konto	Schlüssel des Besitzerkontos verwenden oder GET /api/audits aufrufen
AUDIT_NOT_FOUND (404)	:id existiert nicht	GET /api/audits aufrufen und echte id verwenden
INVALID_URL (400)	:id ist keine positive ganze Zahl	Ganzzahlige id übergeben

Häufig gestellte Fragen

Wie oft sollte ich pollen?

3 bis 5 Sekunden sind der Sweet Spot. Schneller verschwendet Roundtrips; langsamer verzögert den nachgelagerten Kommentar oder die Benachrichtigung. Die meisten Audits sind in den ersten 30 Sekunden fertig; bei 90 Sekunden Schluss und den “läuft noch”-Zustand dem Nutzer melden.

Sind Findings nützlich sortiert?

Sie kommen in Einfügereihenfolge (id aufsteigend), was widerspiegelt, wie die Audit-Pipeline die Module abarbeitet. Für eine menschenlesbare Fix-Liste clientseitig nach severity (critical > major > minor > info) und dann nach Modul sortieren.

Was passiert, wenn ich einen noch laufenden Audit abrufe?

Du bekommst status: "queued" oder status: "running" mit leerem findings-Array und score: null. Die anderen Felder (id, domain, url, created_at) sind ab der ersten Antwort stabil.

Zählt das gegen Plan-Kontingent?

Nein. Nur POST /api/audits (und nur bei Erfolg) dekrementiert den Monatszähler. GET /api/audits/:id ist nicht gemessen.