CoreDash API: Vraag Real User Core Web Vitals Data Op

Je performance data, overal waar je het nodig hebt

CoreDash verzamelt Core Web Vitals van echte gebruikers die je site bezoeken. De API geeft je toegang tot diezelfde data vanuit elke tool, script of AI agent. Drie tools, JSON erin, JSON eruit.

De meest interessante use case: je AI koppelen. De CoreDash API gebruikt hetzelfde protocol als het Model Context Protocol (MCP), wat betekent dat AI tools zoals Claude, Cursor en Windsurf je real user data direct kunnen bevragen. Vraag je AI "waarom is mijn LCP langzaam op mobiel?" en het haalt de daadwerkelijke field data op om te antwoorden.

We hebben CWV Superpowers hierbovenop gebouwd. Het is een AI agent die je CoreDash field data combineert met Chrome DevTools om Core Web Vitals problemen te diagnosticeren en te verhelpen. De API is wat dat mogelijk maakt.

Maar je hebt geen AI agent nodig. Een curl commando werkt net zo goed.

Authenticatie

Elke request heeft een API key nodig in de Authorization header:

Authorization: Bearer cdk_YOUR_API_KEY

Om een key te krijgen:

1. Log in op app.coredash.app
2. Ga naar je project, dan AI Insights, dan Connect Your AI
3. Klik op Create API Key en kopieer deze. Het wordt maar één keer getoond.

Keys beginnen met cdk_ en zijn gescoped op een enkel project. Je kunt meerdere keys aanmaken en deze vanaf dezelfde pagina intrekken.

Request format

De API gebruikt JSON-RPC 2.0. Elke request is een POST naar:

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

De request body ziet er als volgt uit:

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

Het id veld kan elk getal of string zijn. Het wordt teruggestuurd in de response. Er zijn drie tools: get_metrics, get_timeseries en get_histogram.

get_metrics: huidige performance

Geeft de huidige Core Web Vitals waarden terug met good/improve/poor ratings. Dit is de tool die je gebruikt voor "wat is mijn LCP op dit moment?" achtige vragen.

Parameters

Voorbeeld: haal alle metrics op

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": {}
    }
  }'

De ruwe response is een JSON-RPC wrapper:

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

De daadwerkelijke data is een JSON string in het text veld. Geparsed ziet het er zo uit:

{
  "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 }
    }
  }
}

Het distribution object vertelt je welk percentage van de echte page loads in elke rating valt. Dit is vaak nuttiger dan enkel de p75 waarde. Een LCP van 2450ms met 61% good betekent dat de meeste gebruikers een prima ervaring hebben, maar dat de tail de p75 naar beneden trekt.

Voorbeeld: vergelijk mobiele vs desktop LCP

Gebruik de group parameter om resultaten op te splitsen per dimensie. Zo kom je erachter of je LCP probleem een mobiel probleem is:

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 response:

{
  "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 }
        }
      }
    }
  ]
}

Mobiel op 3200ms, desktop op 1800ms. Het totaal zou 2500ms laten zien en je zou denken "niet geweldig, maar niet verschrikkelijk." De gegroepeerde weergave laat het echte verhaal zien: desktop is prima, mobiel heeft werk nodig.

Voorbeeld: filter naar een specifieke pagina op mobiel

Combineer filters om precies het verkeer te specificeren waar je om geeft:

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 over tijd

Geeft metric waarden gebucketed over tijd met automatische trend detectie. Dit is de tool die je gebruikt voor "is mijn LCP slechter geworden?" en "heeft die deploy de regressie gefixt?"

Parameters

Voorbeeld: LCP trend over de laatste 7 dagen

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 response:

{
  "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"
    }
  }
}

De summary vergelijkt de tweede helft van de periode met de eerste helft. Trend waarden zijn improving (meer dan 5% beter), stable (binnen 5%), of regressing (meer dan 5% slechter). Dit is wat het timeseries endpoint nuttig maakt voor geautomatiseerde monitoring: je hoeft niet zelf de datapunten te parsen om te weten of dingen slechter worden.

get_histogram: distributie vorm

Geeft de distributie van een enkele metric terug als ~40 buckets met aantallen per bereik. Dit is de tool die je gebruikt wanneer de p75 er prima uitziet maar je een long tail vermoedt, of wanneer je de volledige vorm van je performance data wilt zien.

Parameters

Let op: in tegenstelling tot get_metrics, vereist dit een enkele metric (geen metrics). Eén metric per request.

Voorbeeld: LCP distributie op mobiel

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 response:

{
  "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
}

Elke bucket heeft from/to grenzen, een count van geschatte page loads in dat bereik, en een rating gebaseerd op waar de bucket zich bevindt ten opzichte van de Core Web Vitals drempelwaarden. De laatste bucket heeft to: null omdat het de open-ended tail is.

Bucket breedtes staan vast per metric: LCP gebruikt 250ms, INP gebruikt 25ms, CLS gebruikt 0.025, FCP gebruikt 200ms, TTFB gebruikt 125ms.

Dit is nuttig om de vorm van je data te begrijpen. Een p75 van 2400ms kan betekenen dat de meeste gebruikers rond de 2400ms zitten, of het kan betekenen dat 60% onder de 1000ms zit en een deel langzaam mobiel verkeer de tail trekt. Het histogram vertelt je welke het is.

Dimensies

Gebruik deze keys in filters of als de group waarde. Filteren beperkt de data tot een specifiek segment. Groeperen splitst de resultaten zodat je segmenten naast elkaar kunt vergelijken.

Algemeen

Apparaat en netwerk

Metric attributie

Deze dimensies vertellen je wat een metric waarde veroorzaakte. Groepeer op lcpel om te zien welke elementen de LCP worden over je pagina's. Groepeer op inpel om de interacties te vinden die de slechtste INP opleveren.

Filter voorbeelden

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

Metrics referentie

De standaard percentile is p75. Dit is wat Google gebruikt voor Core Web Vitals ranking. Als 75% van je page loads onder de drempelwaarde ligt, ben je geslaagd.

De API gebruiken als een MCP server

Het API endpoint is een volledig compatibele MCP server. Als je AI tool MCP ondersteunt (Claude Code, Cursor, Windsurf, en anderen), kun je deze direct koppelen. De AI heeft dan toegang tot get_metrics, get_timeseries en get_histogram als tools en kan je field data bevragen als onderdeel van een conversatie.

Dit is hoe CWV Superpowers werkt: het verbindt met CoreDash via MCP, haalt je real user data op, opent je site in Chrome en traceert de exacte oorzaak van een trage metric. De API levert het "wat gebeurt er in productie" gedeelte, Chrome levert het "waarom gebeurt dit" gedeelte.

Je kunt de MCP server ook aan je eigen AI setup koppelen. Wijs je MCP client naar https://app.coredash.app/api/mcp met je API key, en je AI kan vragen beantwoorden zoals "welke pagina's hebben de slechtste INP op mobiel?" gebruikmakend van daadwerkelijke field data in plaats van te gokken.

Rate limits

Limieten zijn per project per dag en resetten om middernacht UTC.

150 requests op het trial plan is ruim voldoende voor handmatige verkenning en AI geassisteerde debugging. Als je geautomatiseerde monitoring draait in CI, geven de betaalde plannen je er 500 per dag.

Foutafhandeling

Fouten komen terug als JSON-RPC error objecten:

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

Als je -32001 krijgt, controleer of je key begint met cdk_ en dat je deze niet hebt ingetrokken. Als je -32002 krijgt, heb je de dagelijkse limiet bereikt. Wacht op de middernacht UTC reset of upgrade je plan.