PerfDelta API: MCP und REST-API

Stand: 16. Oktober 2026.

PerfDelta bietet zwei Wege, Pagespeed-Messungen automatisiert zu starten, Ihre Projekte zu verwalten und die vollständigen Ergebnisse abzurufen: MCP für KI-Agenten wie Claude, ChatGPT oder Cursor und eine REST-API mit einfachem JSON für Zapier, Make oder eigene Dashboards. Beide nutzen denselben API-Schlüssel und dasselbe Budget wie die App. Wie jeder Wert gemessen wird, beschreibt die Methodik.

Zugang je Tarif

API-Schlüssel legen Sie auf der Seite API-Schlüssel in Ihrem Konto an. Team-Mitglieder nutzen Tarif, Projekte und Budget des Team-Inhabers.

Authentifizierung

Jede Anfrage trägt den API-Schlüssel als Bearer-Token:

Authorization: Bearer IHR_API_KEY

Für den Connector von Claude.ai, der keine Header senden kann, nimmt der MCP-Endpunkt den Schlüssel auch als URL-Parameter: https://perfdelta.com/api/mcp.php?key=IHR_API_KEY. Wer diese URL kennt, kann Ihren Schlüssel nutzen. Halten Sie sie deshalb geheim und widerrufen Sie den Schlüssel, falls sie bekannt wird. Die REST-API akzeptiert nur den Header.

REST: Ohne gültigen Schlüssel antwortet die API mit 401 unauthorized. Nach 20 Fehlversuchen innerhalb von 15 Minuten von derselben IP-Adresse antwortet sie mit 429 too_many_failed_attempts und Retry-After in Sekunden. Ein Tarif ohne Zugang bekommt 403 upgrade_required mit dem Tarif, der ihn enthält. MCP folgt denselben Regeln, antwortet aber mit JSON-RPC-Fehlern, siehe MCP-Fehler. Fehlversuche zählen für MCP und REST getrennt.

Budget und Kosten

• Eine Pagespeed-Abfrage ist ein Lighthouse-Lauf für eine URL auf einem Gerät. Eine Messung von drei URLs auf Mobil und Desktop kostet sechs.
• Messungen über MCP und REST buchen aus demselben Monatsbudget wie das Monitoring und manuelle Messungen in der App. Das Monitoring hat Vorrang: Eine Messung startet nur, wenn sie den Bedarf des Monitorings bis Monatsende nicht anschneidet.
• Für manuelle Messungen, auch über MCP und REST, gilt ein Tagesdeckel von einem Fünftel des Monatsbudgets. Der Tagesdeckel steht um Mitternacht wieder voll bereit, das Monatsbudget am Monatsersten.
• Eine URL aus Ihren Projekten wird in ihrem Projekt gemessen, zusammen mit den übrigen URLs derselben Domain und desselben Takts. Die Kosten umfassen alle diese URLs. Ihre Projekt-Wettbewerber werden über Felddaten aus dem Chrome UX Report verglichen, das kostet keine Pagespeed-Abfragen.
• Reports, Projekte, URLs, Verlauf, Messstand und Verbrauch abzurufen ist kostenlos, ebenso das Verwalten von Projekten, URLs und Wettbewerbern. Hinzugefügte URLs misst das Monitoring aus dem Monatsbudget.
• Jedes Konto kann 60 Anfragen pro Minute senden, für MCP und REST getrennt gezählt. Alle Schlüssel des Kontos und alle Team-Mitglieder teilen sich diese Grenze. Darüber antwortet REST mit 429 rate_limited und MCP mit dem JSON-RPC-Fehler -32003, jeweils mit Retry-After: 60.

Der Parameter devices legt fest, was gemessen wird: both (Standard), mobile oder desktop. Ein einzelnes Gerät halbiert die Kosten.

REST-API

Basis-URL: https://perfdelta.com/api/v1. Alle Antworten sind JSON. Zeiten stehen in deutscher Ortszeit (Europe/Berlin) im Format JJJJ-MM-TT HH:MM:SS.

Messung starten: POST /scans.php

Body als JSON oder formularkodiert: url (absolute, öffentlich erreichbare URL) oder url_id (eine URL aus Ihren Projekten, siehe /urls.php), dazu optional devices, project_id und scope. Kommen beide, gilt url. Mit project_id wird eine URL, die noch in keinem Ihrer Projekte steht, zuerst in dieses Projekt aufgenommen, wie mit „URL hinzufügen“ auf der Projektseite. Sie zählt dann auf Ihr URL-Limit, und die Messung erscheint in Dashboard und Projektverlauf. scope legt den Messumfang fest: url (Standard) misst nur diese URL. group misst alle URLs ihrer Projektgruppe auf derselben Domain wie der Scan-Knopf der Projektseite und kostet je URL und Gerät eine Abfrage. Teilt sich die URL ihre Gruppe mit weiteren URLs, erscheinen nur Gruppenmessungen in ihrem Projektverlauf. Eine Einzelmessung bleibt über scan_id und report_url abrufbar.

curl -X POST -H "Authorization: Bearer IHR_API_KEY" \
  -H "Content-Type: application/json" \
  -d '{"url": "https://example.com/", "devices": "both"}' \
  "https://perfdelta.com/api/v1/scans.php"

Antwort 202:

{
  "scan_id": "7c88c55c1d1bc8f6727d8d19ba9c9a00",
  "status": "running",
  "devices": "both",
  "scope": "url",
  "measured_urls": 1,
  "cost": 2,
  "report_url": "https://perfdelta.com/en/r/example.com/7c88c55c-1d1b-c8f6-727d-8d19ba9c9a00",
  "budget_remaining": 11936,
  "daily_remaining": 2398,
  "project_id": 3,
  "url_id": 41,
  "added_to_project": true
}

budget_remaining ist, was in diesem Monat nach dem Bedarf des Monitorings für manuelle Messungen, MCP und REST übrig bleibt; daily_remaining ist der Rest des heutigen Tagesdeckels. project_id und url_id nennen die Projekt-URL, zu der die Messung gehört (null bei einer URL außerhalb Ihrer Projekte); added_to_project ist true, wenn diese Anfrage die URL aufgenommen hat. scope wiederholt den Messumfang, measured_urls nennt die Zahl der URLs dieser Messung.

Messstand und Ergebnis: GET /scans.php?id={scan_id}

Liefert status (running, done oder error), started_at und report_url. Bei running kommen step, step_total, step_msg, updated_at und die bereits gemessenen pages (Format wie unten) hinzu, damit sich eine langsame von einer stehenden Messung unterscheiden lässt und fertige Seiten früh lesbar sind; bei error das Feld error. Bei done kommen mobile_score, desktop_score (durchschnittlicher Laborwert der gemessenen Seiten von 0 bis 100, null für ein nicht gemessenes Gerät), measured_at und pages hinzu: je gemessener Seite und Gerät ein Eintrag mit url, device, score, lab (lcp_ms, cls, fcp_ms, tbt_ms, ttfb_ms aus Lighthouse) und field (lcp_ms, inp_ms, cls, fcp_ms, ttfb_ms am 75. Perzentil echter Chrome-Nutzer, null ohne ausreichende Felddaten). Eine Messung dauert meist ein bis drei Minuten; fragen Sie alle 15 bis 30 Sekunden ab. Nur das Konto, das die Messung gestartet hat, kann sie abrufen, jeder andere Schlüssel bekommt 404. Die id darf auch mit Bindestrichen wie in report_url geschrieben sein; Groß- und Kleinschreibung spielt keine Rolle.

curl -H "Authorization: Bearer IHR_API_KEY" \
  "https://perfdelta.com/api/v1/scans.php?id=7c88c55c1d1bc8f6727d8d19ba9c9a00"

Budget: GET /usage.php

Felder: plan, unit (immer PageSpeed tests (one per URL and device)), daily_limit, daily_used, daily_remaining, monthly_budget, monthly_used, monitoring_projected (Bedarf des Monitorings pro Monat mit den aktuellen Einstellungen), monitoring_remaining_need (Bedarf bis Monatsende), available_for_manual_scans und upgrade_plan (nächster Tarif mit mehr Kapazität, null bei Scale). Alle Werte sind Pagespeed-Abfragen. Ohne Monatsbudget ist monthly_budget gleich null, und die vier Felder von monthly_used bis available_for_manual_scans entfallen.

Daten abrufen

curl -H "Authorization: Bearer IHR_API_KEY" \
  "https://perfdelta.com/api/v1/report.php?url=https%3A%2F%2Fexample.com%2F"

Vollständiger Report: GET /details.php?id={scan_id}

Dieselbe Antwort wie das MCP-Tool get_report_details, beschrieben weiter unten: alles, was die Report-Seite ihrem Eigentümer zeigt. id ist eine scan_id aus /scans.php oder /report.php oder ein hash aus /history.php; alternativ liefert url_id die neueste Messung einer Projekt-URL. Abrufbar sind selbst gestartete Messungen und jede Messung einer URL aus Ihren Projekten, auch Monitoring-Läufe. Jede andere Messung antwortet mit 404 not_found, eine Anfrage ohne id und url_id mit 422 missing_id. Kostenlos.

curl -H "Authorization: Bearer IHR_API_KEY" \
  "https://perfdelta.com/api/v1/details.php?id=7c88c55c1d1bc8f6727d8d19ba9c9a00"

Projekte, URLs, Wettbewerber und Notizen verwalten

Es gelten dieselben Regeln wie in der App: Tarife ohne mehrere Projekte haben ein Projekt, URLs zählen über alle Projekte gegen das URL-Limit Ihres Tarifs, angenommen werden nur öffentliche http(s)-URLs, und die Zahl der Wettbewerber je Projekt hängt vom Tarif ab. Bodys sind JSON; POST nimmt auch Formularfelder an.

curl -X POST -H "Authorization: Bearer IHR_API_KEY" \
  -H "Content-Type: application/json" \
  -d '{"project_id": 6, "urls": ["https://example.com/", "https://example.com/preise/"]}' \
  "https://perfdelta.com/api/v1/urls.php"

Performance-Budgets als CI-Gate: /budgets.php

Ein Performance-Budget ist eine Grenze, die eine Seite nicht überschreiten darf, etwa Seitengewicht höchstens 1,5 MB, JavaScript höchstens 400 KB, LCP im Labor höchstens 2,5 s oder ein Lab-Score von mindestens 80. Budgets gelten je Projekt (alle URLs) oder je Projekt-URL, die dann für diese URL das Projekt-Budget ersetzt. Jedes Budget kann ein Ziel tragen; Ziele stehen neben dem Ergebnis und lassen keine Prüfung scheitern. Bewertet werden Werte, die jede Messung ohnehin liefert, eine Prüfung kostet also nichts über die Messung hinaus. Enthalten in allen bezahlten Tarifen; für den REST-Endpunkt gelten die REST-Regeln oben.

Kennzahlen: total_kb, script_kb, image_kb, stylesheet_kb, font_kb, third_party_kb, third_party_count, request_count, perf_score (Mindestwert), lab_lcp_ms, tbt_ms, lab_cls, fcp_ms, ttfb_ms und aus Felddaten (CrUX p75, nur mobil) field_lcp_ms, field_inp_ms, field_cls. limit und goal sind Zahlen in der Einheit der Kennzahl (KB, ms, Punkte, Anzahl, CLS) oder Text mit Einheit wie "1.5 MB" oder "2.5 s". Nicht zu verwechseln mit dem monatlichen Budget an Pagespeed-Abfragen in /usage.php.

curl -X POST -H "Authorization: Bearer YOUR_API_KEY" \
  -H "Content-Type: application/json" \
  -d '{"project_id": 6, "metric": "script_kb", "device": "mobile", "limit": "400 KB", "goal": 300}' \
  "https://perfdelta.com/api/v1/budgets.php"

Eine Prüfung in der Deployment-Pipeline, etwa als Schritt in GitHub Actions nach dem Deploy auf Staging: Messung der URL starten, warten, bis sie fertig ist, dann die Budgets prüfen.

SCAN=$(curl -s -X POST -H "Authorization: Bearer $PERFDELTA_API_KEY" \
  -H "Content-Type: application/json" -d '{"url": "https://staging.example.com/"}' \
  "https://perfdelta.com/api/v1/scans.php" | jq -r .scan_id)
until [ "$(curl -s -H "Authorization: Bearer $PERFDELTA_API_KEY" \
  "https://perfdelta.com/api/v1/scans.php?id=$SCAN" | jq -r .status)" != "running" ]; do sleep 20; done
curl --fail -s -H "Authorization: Bearer $PERFDELTA_API_KEY" \
  "https://perfdelta.com/api/v1/budgets.php?scan_id=$SCAN&fail_status=1"

Fehlercodes

Fehler haben die Form {"error": "code"}. Fehler beim Start einer Messung, beim Anlegen oder Ändern von Projekten, URLs, Wettbewerbern und Notizen sowie upgrade_required bringen zusätzlich eine message mit, Messfehler je nach Fall weitere Angaben aus der Tabelle. Die Meldungen sind englisch.

MCP für KI-Agenten

Endpunkt: https://perfdelta.com/api/mcp.php. Der Transport ist Streamable HTTP mit JSON-RPC 2.0, zustandslos: Jede Anfrage ist ein einzelnes POST mit JSON-Body und bekommt eine JSON-Antwort. Es gibt keine Mcp-Session-Id und keinen SSE-Stream; GET antwortet mit 405. Unterstützte Protokollversionen: 2026-07-28, 2025-11-25, 2025-06-18, 2025-03-26 und 2024-11-05. Der Server beantwortet initialize mit der Version, die der Client verlangt, bei einer unbekannten mit 2026-07-28, und liefert instructions zu Kosten und Ablauf mit.

initialize, notifications/initialized, ping und tools/list funktionieren ohne Schlüssel, damit Clients und Verzeichnisse die Tool-Liste vor der Anmeldung lesen können. tools/call verlangt einen Schlüssel. Ein mitgeschickter, aber ungültiger Schlüssel wird bei jeder Methode abgewiesen. Sendet ein Client die optionalen Header Mcp-Method oder Mcp-Name, müssen sie zu Methode und Tool-Namen im Body passen.

Einrichtung

Claude Code:

claude mcp add --transport http perfdelta https://perfdelta.com/api/mcp.php \
  --header "Authorization: Bearer IHR_API_KEY"

Oder in der .mcp.json eines Projekts:

{
  "mcpServers": {
    "perfdelta": {
      "type": "http",
      "url": "https://perfdelta.com/api/mcp.php",
      "headers": { "Authorization": "Bearer IHR_API_KEY" }
    }
  }
}

Cursor: derselbe Block ohne "type" in .cursor/mcp.json. VS Code: in .vscode/mcp.json unter "servers" statt "mcpServers", mit "type": "http".

Claude.ai und Claude Desktop: Einstellungen, Connectors, eigenen Connector hinzufügen, mit der Connector-URL https://perfdelta.com/api/mcp.php?key=IHR_API_KEY. ChatGPT (Entwicklermodus): Einstellungen, Connectors, Erstellen, mit derselben URL samt ?key= und ohne Authentifizierung, weil der Dialog keine eigenen Header anbietet.

Tools

Ergebnisse kommen als ein Textblock mit JSON. Anders als bei REST liefern list_projects, list_urls und list_competitors die Liste direkt, ohne umschließendes Objekt. Typischer Ablauf für einen Agenten: get_usage, dann scan_url, dann get_scan alle 15 bis 30 Sekunden bis done, danach get_report_details für den vollständigen Report. Für ein Monitoring: create_project, add_urls, bei Bedarf add_competitor.

Vollständiger Report: get_report_details

Liefert alles, was die Report-Seite dem Eigentümer zeigt, als JSON zur Auswertung durch eine KI: summary (Scores, vorherige Scores, Seiten mit bestandenen Core Web Vitals je Gerät, Schwellen, globale Bestehensquote, größter Engpass), origin_field_data und origin_field_history (CrUX für die ganze Domain), competitors, perfdelta_average, industry_benchmark (Tarife mit Branchenvergleich), pages, tech_stack, ai_recommendations, notes und history. Jeder Eintrag in pages steht für eine URL und ein Gerät: score, field und lab mit Bewertung je Messwert (good, ni, poor), field_distribution, cwv_pass, page_weight_bytes, resource_breakdown, third_parties, opportunities mit geschätzter Ersparnis und diagnostics (LCP-Element, Layout-Verschiebungen, Main-Thread-Arbeit, Skript-Bundles, größte Anfragen). screenshots und filmstrip (jeweils mobile und desktop) enthalten absolute Bild-URLs, Filmstreifen-Bilder mit url und timing_ms. notes listet Ihre eigenen Notizen mit id, note, created_at, passend zu update_note und delete_note. Funktioniert für Messungen in Ihren Projekten und für Messungen, die Ihr Konto gestartet hat; für andere Domains gibt es get_report. Die Felder im Einzelnen: Oben stehen complete (true, sobald die Messung done ist) und purged (true, wenn die Seitendaten einer alten Messung gelöscht sind). summary enthält mobile_score, desktop_score, previous_mobile_score, previous_desktop_score, cwv_pages_passing (je Gerät pass und total), cwv_thresholds, global_cwv_pass_rate (mit source) und biggest_bottleneck. Jede Seite hat field_is_origin_fallback (true: Werte der ganzen Domain, die Seite hatte keine eigenen Felddaten), field_distribution mit dist-Anteilen je Metrik, request_count und je Optimierung id, title, savings_ms und resources; der score der Seite ist der Lighthouse-performance_score. ai_recommendations_lang nennt die Sprache der Empfehlungen.

MCP-Fehler

Fehler innerhalb eines Tools kommen als normales Tool-Ergebnis mit isError: true und einem Meldungstext, ohne den REST-Fehlercode und dessen Zusatzangaben. Beispiele: unbekannte scan_id, project_id, url_id oder competitor_id, fehlende url, ein erreichtes Projekt-, URL- oder Wettbewerberlimit, erschöpftes Budget oder ein Tarif ohne MCP-Zugang (mit dem Tarif, der ihn enthält). Scheitert scan_url an Budget oder Tagesdeckel, endet der Text mit dem Link zur Preisseite. Protokollfehler nutzen JSON-RPC-Fehlercodes und tragen die id der Anfrage, sofern sie lesbar ist:

Fragen oder eine Antwort, die nicht zu dieser Seite passt: Kontaktformular.