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, elk script of elke AI agent. Drie tools, JSON in, JSON out.

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 opvragen. Vraag je AI "waarom is mijn LCP traag op mobiel?" en het haalt de daadwerkelijke field data op om antwoord te geven.

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 op te lossen. De API maakt dat mogelijk.

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

Run je een agency of beheer je veel projecten vanuit één account? Er is een aparte Agency API die een master key gebruikt om projecten aan te maken, bij te werken en te verwijderen, en om data over alle projecten heen op te halen met één enkele key. De rest van deze pagina behandelt de data API per project.

Authenticatie

Elk verzoek 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, vervolgens AI Insights, en dan Connect Your AI
3. Klik op Create API Key en kopieer deze. Hij wordt maar één keer getoond.

Keys beginnen met cdk_ en zijn beperkt tot één enkel project. Je kunt meerdere keys aanmaken en ze intrekken vanaf dezelfde pagina.

Request formaat

De API gebruikt JSON-RPC 2.0. Elk verzoek 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 willekeurig getal of string zijn. Deze wordt teruggegeven 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 beoordelingen. Dit is de tool die je gebruikt voor vragen als "wat is mijn LCP op dit moment?".

Parameters

Voorbeeld: alle metrics ophalen

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 binnen het text veld. Na het parsen ziet dit 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 binnen elke beoordeling 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 de staart trekt de p75 omlaag.

Voorbeeld: vergelijk mobiele vs desktop LCP

Gebruik de group parameter om resultaten te splitsen op basis van een willekeurige 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"
      }
    }
  }'

Geparste 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, waardoor je zou denken "niet geweldig, maar niet dramatisch". De gegroepeerde weergave vertelt het echte verhaal: desktop is prima, mobiel heeft werk nodig.

Voorbeeld: filteren op een specifieke pagina op mobiel

Combineer filters om precies te focussen op het verkeer dat jij belangrijk vindt:

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 terug gegroepeerd over tijd met automatische trenddetectie. Dit is de tool die je gebruikt voor vragen als "is mijn LCP slechter geworden?" en "heeft die deploy de regressie opgelost?".

Parameters

Voorbeeld: LCP trend van de afgelopen 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"
      }
    }
  }'

Geparste 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. Trendwaarden zijn improving (meer dan 5% beter), stable (binnen de 5%) of regressing (meer dan 5% slechter). Dit maakt het timeseries endpoint zo nuttig voor automatische monitoring: je hoeft de datapunten niet zelf te parsen om te weten of de situatie verslechtert.

get_histogram: vorm van de verdeling

Geeft de verdeling van een enkele metric terug als ~40 buckets met tellingen per reeks. Dit is de tool die je gebruikt wanneer de p75 in orde lijkt maar je een lange staart vermoedt, of wanneer je de volledige vorm van je performance data wilt zien.

Parameters

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

Voorbeeld: LCP verdeling 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"
      }
    }
  }'

Geparste 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 die reeks en een rating gebaseerd op waar de bucket zich bevindt ten opzichte van de Core Web Vitals limieten. De laatste bucket heeft to: null omdat dit de open staart 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 traag mobiel verkeer de staart uitrekt. Het histogram vertelt je welk van de twee 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 veroorzaakt heeft. Groepeer op lcpel om te zien welke elementen de LCP worden op 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

Het standaard percentiel is p75. Dit is wat Google gebruikt voor de Core Web Vitals ranking. Als 75% van je page loads onder de limiet zit, slaag je.

De API als MCP server gebruiken

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 opvragen als onderdeel van elk gesprek.

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 het" gedeelte.

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

Rate limits

Limieten zijn per project per dag en worden gereset om middernacht UTC.

150 verzoeken op het trial pakket is ruim voldoende voor handmatige verkenning en AI geassisteerde debugging. Als je geautomatiseerde monitoring draait in CI, geven de betaalde pakketten 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 dan 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 reset om middernacht UTC of upgrade je pakket.