CoreDash API: Core Web Vitals Daten von echten Nutzern abfragen

Ihre Performance-Daten, wo immer Sie sie brauchen

CoreDash sammelt Core Web Vitals von echten Nutzern, die Ihre Website besuchen. Die API gibt Ihnen Zugriff auf genau diese Daten von jedem Tool, Skript oder KI-Agenten aus. Drei Tools, JSON rein, JSON raus.

Der interessanteste Anwendungsfall: Die Anbindung Ihrer KI. Die CoreDash API nutzt dasselbe Protokoll wie das Model Context Protocol (MCP), was bedeutet, dass KI-Tools wie Claude, Cursor und Windsurf Ihre echten Nutzerdaten direkt abfragen können. Fragen Sie Ihre KI „Warum ist mein LCP auf Mobilgeräten langsam?“ und sie ruft die tatsächlichen Felddaten ab, um zu antworten.

Darauf aufbauend haben wir CWV Superpowers entwickelt. Es handelt sich um einen KI-Agenten, der Ihre CoreDash Felddaten mit den Chrome DevTools kombiniert, um Core Web Vitals Probleme zu diagnostizieren und zu beheben. Die API ist das, was dies möglich macht.

Aber Sie brauchen keinen KI-Agenten. Ein curl-Befehl funktioniert genauso gut.

Authentifizierung

Jede Anfrage benötigt einen API-Schlüssel im Authorization-Header:

Authorization: Bearer cdk_YOUR_API_KEY

Um einen Schlüssel zu erhalten:

1. Melden Sie sich unter app.coredash.app an
2. Gehen Sie zu Ihrem Projekt, dann zu AI Insights und dann auf Connect Your AI
3. Klicken Sie auf Create API Key und kopieren Sie ihn. Er wird nur einmal angezeigt.

Schlüssel beginnen mit cdk_ und sind auf ein einzelnes Projekt beschränkt. Sie können mehrere Schlüssel erstellen und sie auf derselben Seite widerrufen.

Anfrageformat

Die API verwendet JSON-RPC 2.0. Jede Anfrage ist ein POST an:

https://app.coredash.app/api/mcp

Der Anfragetext (Body) sieht so aus:

{
  "jsonrpc": "2.0",
  "id": 1,
  "method": "tools/call",
  "params": {
    "name": "get_metrics",
    "arguments": { }
  }
}

Das id-Feld kann eine beliebige Zahl oder Zeichenfolge sein. Es wird in der Antwort zurückgegeben. Es gibt drei Tools: get_metrics, get_timeseries und get_histogram.

get_metrics: aktuelle Performance

Gibt die aktuellen Core Web Vitals Werte mit Bewertungen (good/improve/poor) zurück. Dies ist das Tool, das Sie für Fragen der Art „Wie ist mein LCP im Moment?“ verwenden.

Parameter

Beispiel: Alle Metriken abrufen

curl -X POST https://app.coredash.app/api/mcp \
  -H "Content-Type: application/json" \
  -H "Authorization: Bearer cdk_YOUR_API_KEY" \
  -d '{
    "jsonrpc": "2.0",
    "id": 1,
    "method": "tools/call",
    "params": {
      "name": "get_metrics",
      "arguments": {}
    }
  }'

Die rohe Antwort ist ein JSON-RPC-Wrapper:

{
  "jsonrpc": "2.0",
  "id": 1,
  "result": {
    "content": [{
      "type": "text",
      "text": "{ ... JSON string ... }"
    }]
  }
}

Die eigentlichen Daten sind ein JSON-String innerhalb des text-Feldes. Geparsed sieht das so aus:

{
  "period": "last 31 days",
  "percentile": "p75",
  "metrics": {
    "LCP": {
      "value": 2450,
      "unit": "ms",
      "rating": "improve",
      "distribution": { "good": 61.2, "improve": 22.4, "poor": 16.4 }
    },
    "INP": {
      "value": 180,
      "unit": "ms",
      "rating": "good",
      "distribution": { "good": 82.1, "improve": 12.3, "poor": 5.6 }
    },
    "CLS": {
      "value": 0.08,
      "unit": "",
      "rating": "good",
      "distribution": { "good": 74.5, "improve": 18.2, "poor": 7.3 }
    }
  }
}

Das distribution-Objekt sagt Ihnen, welcher Prozentsatz der echten Seitenaufrufe in die jeweilige Bewertung fällt. Dies ist oft nützlicher als der p75-Wert allein. Ein LCP von 2450ms mit 61 % „good“ bedeutet, dass die meisten Nutzer eine gute Erfahrung haben, aber der Endbereich (Tail) zieht den p75-Wert nach unten.

Beispiel: Mobile vs. Desktop LCP vergleichen

Verwenden Sie den Parameter group, um Ergebnisse nach einer beliebigen Dimension aufzuteilen. So finden Sie heraus, ob Ihr LCP-Problem ein rein mobiles Problem ist:

curl -X POST https://app.coredash.app/api/mcp \
  -H "Content-Type: application/json" \
  -H "Authorization: Bearer cdk_YOUR_API_KEY" \
  -d '{
    "jsonrpc": "2.0",
    "id": 2,
    "method": "tools/call",
    "params": {
      "name": "get_metrics",
      "arguments": {
        "metrics": "LCP",
        "group": "d",
        "date": "-7d"
      }
    }
  }'

Geparsede Antwort:

{
  "period": "last 7 days",
  "percentile": "p75",
  "groupedBy": "d",
  "groupName": "Device Type",
  "segments": [
    {
      "segment": "mobile",
      "value": "mobile",
      "metrics": {
        "LCP": {
          "value": 3200, "unit": "ms", "rating": "improve",
          "distribution": { "good": 52.3, "improve": 28.1, "poor": 19.6 }
        }
      }
    },
    {
      "segment": "desktop",
      "value": "desktop",
      "metrics": {
        "LCP": {
          "value": 1800, "unit": "ms", "rating": "good",
          "distribution": { "good": 78.5, "improve": 15.2, "poor": 6.3 }
        }
      }
    }
  ]
}

Mobile bei 3200ms, Desktop bei 1800ms. Der aggregierte Wert würde 2500ms anzeigen und Sie würden denken: „Nicht großartig, aber auch nicht schrecklich.“ Die gruppierte Ansicht zeigt die wahre Geschichte: Desktop ist in Ordnung, Mobile erfordert Arbeit.

Beispiel: Auf eine bestimmte Seite auf Mobilgeräten filtern

Kombinieren Sie filters, um genau den Traffic einzugrenzen, der Sie interessiert:

curl -X POST https://app.coredash.app/api/mcp \
  -H "Content-Type: application/json" \
  -H "Authorization: Bearer cdk_YOUR_API_KEY" \
  -d '{
    "jsonrpc": "2.0",
    "id": 3,
    "method": "tools/call",
    "params": {
      "name": "get_metrics",
      "arguments": {
        "metrics": "LCP,CLS",
        "filters": { "ff": "/checkout", "d": "mobile" },
        "date": "-7d"
      }
    }
  }'

get_timeseries: Performance im Zeitverlauf

Gibt Metrikwerte zurück, die über die Zeit gebucketed (zusammengefasst) wurden, mit automatischer Trenderkennung. Dies ist das Tool, das Sie für Fragen wie „Ist mein LCP schlechter geworden?“ und „Hat dieses Deployment die Regression behoben?“ verwenden.

Parameter

Beispiel: LCP-Trend der letzten 7 Tage

curl -X POST https://app.coredash.app/api/mcp \
  -H "Content-Type: application/json" \
  -H "Authorization: Bearer cdk_YOUR_API_KEY" \
  -d '{
    "jsonrpc": "2.0",
    "id": 4,
    "method": "tools/call",
    "params": {
      "name": "get_timeseries",
      "arguments": {
        "metrics": "LCP",
        "date": "-7d",
        "granularity": "day"
      }
    }
  }'

Geparsede Antwort:

{
  "period": "last 7 days",
  "percentile": "p75",
  "granularity": "day",
  "dataPoints": 7,
  "timeseries": [
    { "date": "2026-03-10T00:00:00.000Z", "LCP": { "value": 2600, "unit": "ms", "rating": "improve" } },
    { "date": "2026-03-11T00:00:00.000Z", "LCP": { "value": 2450, "unit": "ms", "rating": "improve" } },
    { "date": "2026-03-12T00:00:00.000Z", "LCP": { "value": 2300, "unit": "ms", "rating": "good" } }
  ],
  "summary": {
    "LCP": {
      "recent": 2350,
      "previous": 2680,
      "change": -12.3,
      "trend": "improving",
      "unit": "ms"
    }
  }
}

Das summary vergleicht die zweite Hälfte des Zeitraums mit der ersten Hälfte. Trendwerte sind improving (mehr als 5 % besser), stable (innerhalb von 5 %) oder regressing (mehr als 5 % schlechter). Das macht den Timeseries-Endpunkt so nützlich für automatisiertes Monitoring: Sie müssen die Datenpunkte nicht selbst parsen, um zu wissen, ob sich die Dinge verschlechtern.

get_histogram: Verteilungsform

Gibt die Verteilung einer einzelnen Metrik als ~40 Buckets mit Zählungen pro Bereich zurück. Dies ist das Tool, das Sie verwenden, wenn der p75-Wert in Ordnung aussieht, Sie aber einen langen Tail vermuten, oder wenn Sie die vollständige Form Ihrer Performance-Daten sehen möchten.

Parameter

Hinweis: Im Gegensatz zu get_metrics erfordert dies ein einzelnes metric (nicht metrics). Eine Metrik pro Anfrage.

Beispiel: LCP-Verteilung auf Mobilgeräten

curl -X POST https://app.coredash.app/api/mcp \
  -H "Content-Type: application/json" \
  -H "Authorization: Bearer cdk_YOUR_API_KEY" \
  -d '{
    "jsonrpc": "2.0",
    "id": 5,
    "method": "tools/call",
    "params": {
      "name": "get_histogram",
      "arguments": {
        "metric": "LCP",
        "filters": { "d": "mobile" },
        "date": "-7d"
      }
    }
  }'

Geparsede Antwort:

{
  "period": "last 7 days",
  "metric": "LCP",
  "unit": "ms",
  "filters": { "d": "mobile" },
  "buckets": [
    { "from": 0, "to": 250, "count": 1250, "rating": "good" },
    { "from": 250, "to": 500, "count": 3400, "rating": "good" },
    { "from": 500, "to": 750, "count": 2800, "rating": "good" },
    { "from": 2500, "to": 2750, "count": 890, "rating": "improve" },
    { "from": 4000, "to": 4250, "count": 120, "rating": "poor" },
    { "from": 9750, "to": null, "count": 15, "rating": "poor" }
  ],
  "total": 45000
}

Jedes Bucket hat from/to-Grenzen, einen count der geschätzten Seitenaufrufe in diesem Bereich und ein rating basierend darauf, wo das Bucket im Verhältnis zu den Core Web Vitals-Grenzwerten liegt. Das letzte Bucket hat to: null, weil es der offene Tail (Endbereich) ist.

Die Bucket-Breiten sind pro Metrik festgelegt: LCP verwendet 250ms, INP verwendet 25ms, CLS verwendet 0.025, FCP verwendet 200ms, TTFB verwendet 125ms.

Dies ist nützlich, um die Form Ihrer Daten zu verstehen. Ein p75 von 2400ms könnte bedeuten, dass die meisten Nutzer bei etwa 2400ms liegen, oder es könnte bedeuten, dass 60 % unter 1000ms liegen und ein Teil des langsamen mobilen Traffics den Tail nach unten zieht. Das Histogramm verrät Ihnen, was zutrifft.

Dimensionen

Verwenden Sie diese Schlüssel in filters oder als group-Wert. Filtern grenzt die Daten auf ein bestimmtes Segment ein. Gruppieren teilt die Ergebnisse auf, sodass Sie Segmente nebeneinander vergleichen können.

Allgemein

Gerät und Netzwerk

Metrik-Zuordnung (Attribution)

Diese Dimensionen verraten Ihnen, was einen Metrikwert verursacht hat. Gruppieren Sie nach lcpel, um zu sehen, welche Elemente auf Ihren Seiten das LCP werden. Gruppieren Sie nach inpel, um die Interaktionen zu finden, die das schlechteste INP erzeugen.

Filter-Beispiele

{ "d": "mobile" }
{ "ff": "/checkout", "d": "desktop" }
{ "cc": "US", "browser": "Chrome" }
{ "u": "[neq]*/admin/*" }

Metrik-Referenz

Das Standard-Perzentil ist p75. Dies ist, was Google für das Core Web Vitals Ranking verwendet. Wenn 75 % Ihrer Seitenaufrufe unter dem Grenzwert liegen, bestehen Sie.

Die API als MCP-Server nutzen

Der API-Endpunkt ist ein vollständig kompatibler MCP-Server. Wenn Ihr KI-Tool MCP unterstützt (Claude Code, Cursor, Windsurf und andere), können Sie es direkt verbinden. Die KI hat dann Zugriff auf get_metrics, get_timeseries und get_histogram als Werkzeuge und kann Ihre Felddaten als Teil jeder Konversation abfragen.

So funktioniert CWV Superpowers: Es verbindet sich über MCP mit CoreDash, zieht Ihre echten Nutzerdaten, öffnet Ihre Website in Chrome und spürt die genaue Ursache einer langsamen Metrik auf. Die API liefert den Teil „Was passiert in der Produktion“, Chrome liefert den Teil „Warum passiert das“.

Sie können den MCP-Server auch mit Ihrem eigenen KI-Setup verbinden. Richten Sie Ihren MCP-Client mit Ihrem API-Schlüssel auf https://app.coredash.app/api/mcp, und Ihre KI kann Fragen wie „Welche Seiten haben das schlechteste INP auf Mobilgeräten?“ anhand tatsächlicher Felddaten beantworten, anstatt zu raten.

Rate Limits (Ratenbegrenzungen)

Die Limits gelten pro Projekt und pro Tag und werden um Mitternacht UTC zurückgesetzt.

150 Anfragen im Trial-Plan sind für die manuelle Erkundung und das KI-gestützte Debugging völlig ausreichend. Wenn Sie automatisiertes Monitoring in der CI ausführen, bieten Ihnen die kostenpflichtigen Pläne 500 pro Tag.

Fehlerbehandlung (Error Handling)

Fehler werden als JSON-RPC-Fehlerobjekte zurückgegeben:

{
  "jsonrpc": "2.0",
  "id": 1,
  "error": { "code": -32001, "message": "Invalid or revoked API key." }
}

Wenn Sie -32001 erhalten, überprüfen Sie, ob Ihr Schlüssel mit cdk_ beginnt und Sie ihn nicht widerrufen haben. Wenn Sie -32002 erhalten, haben Sie das Tageslimit erreicht. Warten Sie auf den Reset um Mitternacht UTC oder führen Sie ein Upgrade Ihres Plans durch.