GET /api/audits

Was dieser Endpunkt macht

GET /api/audits liefert die jüngsten Audits des authentifizierten Kontos, dedupliziert nach URL. Wenn du dieselbe URL zehnmal auditiert hast, bekommst du eine Zeile zurück: die neueste. Die Liste ist sortiert nach der vom Nutzer gespeicherten Anzeigeposition (im Dashboard gesetzt) und dann nach created_at absteigend.

• Nach URL dedupliziert: eine Zeile pro einzigartiger URL.
• Sortiert nach display_position ASC NULLS LAST, created_at DESC.
• Liefert standardmäßig bis zu 100 Zeilen. Keine limit oder offset-Parameter in v1; das Dashboard zieht dieselbe Form.
• Günstig und idempotent: keine Plan-Kosten, kein PSI, kein Crawler-Aufruf.

Warum das wichtig ist

Das ist der Endpunkt, den ein Dashboard, ein wöchentlicher Digest oder ein CI-Dashboard zuerst trifft. Er liefert jede URL, die dem Konto wichtig ist, mit ihrem aktuellen Score, bereit zur Verknüpfung mit GET /api/audits/:id für den vollen Envelope oder mit POST /api/audits für ein frisches Re-Run.

Konkrete Workflows:

• Ein wöchentlicher Zapier-Zap ruft GET /api/audits auf, vergleicht Scores mit dem Vorwochen-Snapshot in Airtable und postet eine Slack-Nachricht für jede URL, die mehr als 5 Punkte verloren hat.
• Ein internes CI-Dashboard pollt jede Minute und rendert ein Statusraster nach display_position, damit die wichtigsten Seiten oben stehen.

Wie du ihn nutzt

Bearer-Auth Pflicht. Keine Query-Parameter.

Request

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

curl

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

Node fetch

const res = await fetch("https://app.metricspot.com/api/audits", {
  headers: { authorization: "Bearer ms_live_xxxxxxxxxxxxxxxxxxxxxxxx" },
});
const { audits } = await res.json();
for (const a of audits) {
  console.log(a.score, a.url);
}

Python httpx

import httpx

r = httpx.get(
    "https://app.metricspot.com/api/audits",
    headers={"authorization": "Bearer ms_live_xxxxxxxxxxxxxxxxxxxxxxxx"},
    timeout=30.0,
)
for a in r.json()["audits"]:
    print(f"{a['score'] or '..'} {a['url']} ({a['status']})")

Antwort

200 OK:

{
  "audits": [
    {
      "id": 12345,
      "domain": "example.com",
      "url": "https://example.com",
      "status": "completed",
      "score": 78,
      "created_at": "2026-05-14T10:18:04.000Z",
      "completed_at": "2026-05-14T10:18:24.000Z",
      "display_position": 0
    },
    {
      "id": 12321,
      "domain": "example.com",
      "url": "https://example.com/pricing",
      "status": "completed",
      "score": 71,
      "created_at": "2026-05-13T09:02:11.000Z",
      "completed_at": "2026-05-13T09:02:34.000Z",
      "display_position": 1
    }
  ]
}

Felder pro Zeile:

• id: ganzzahlige Audit-ID, in Folgeaufrufen verwendet.
• domain: Hostname.
• url: volle auditierte URL.
• status: einer aus queued, running, completed, failed.
• score: ganze Zahl 0 bis 100, oder null während Queue oder Run.
• created_at: ISO 8601-Zeitstempel.
• completed_at: ISO 8601-Zeitstempel, oder null wenn noch nicht fertig.
• display_position: ganzzahliger Rang per Drag-and-Drop im Dashboard, oder null wenn der Nutzer nicht sortiert hat. Der Endpunkt sortiert primär nach diesem Feld.

Der Endpunkt liefert immer {"audits": [...]}. Kein Paging-Envelope; das Cap sind 100 Zeilen. POST /api/audits gefolgt von GET /api/audits/:id für vollständige Per-Audit-Details verwenden.

Fehler-Envelope

{ "error": "Unauthorized" }

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
UPSTREAM_FAILED (5xx)	Datenbank-Aussetzer	Mit Backoff einmal erneut versuchen

Der Endpunkt liefert nie 404 oder 429: er ist eine Liste deiner eigenen Ressourcen ohne Rate Limit über den Plan hinaus.

Häufig gestellte Fragen

Warum ist die Liste nach URL dedupliziert?

Das Dashboard zeigt eine Karte pro URL: erneutes Auditieren derselben URL ersetzt den Score der vorherigen Karte. Die API spiegelt diese Sicht exakt, damit eine Dritt-UI dieselbe Liste rendern kann, ohne die Deduplizierung neu zu implementieren.

Wie bekomme ich jeden Audit (inklusive älterer Läufe derselben URL)?

Den Per-URL-History-Endpunkt im Detail eines Audits verwenden. Die Liste ist absichtlich “neuester pro URL”, weil das ist, was Dashboards und Digests brauchen. Eine künftige Revision kann eine flache, unpaginierte Historie freigeben.

Ist display_position per API editierbar?

Ja, indirekt: das Drag-and-Drop im Dashboard mappt auf einen separaten Reorder-Endpunkt, der ein Array von URLs in der neuen Reihenfolge entgegennimmt. Die Liste liest die gespeicherten Positionen; sie schreibt sie nicht.

Zählt das gegen Plan-Kontingent?

Nein. Der List-Endpunkt ist nicht gemessen. Nur POST /api/audits (und nur bei Erfolg) dekrementiert den Monatszähler.