CoreDash API: Vraag echte gebruikers Core Web Vitals data op

Jouw performance data, overal waar je het nodig hebt

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

De meest interessante use case: het verbinden van je AI. De CoreDash API gebruikt hetzelfde protocol als het Model Context Protocol (MCP), wat betekent dat AI tools zoals Claude, Cursor en Windsurf je echte gebruikersdata 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 hier bovenop gebouwd. Het is een AI agent die jouw CoreDash field data combineert met Chrome DevTools om Core Web Vitals problemen te diagnosticeren en op te lossen. De API is wat dat mogelijk maakt.

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 van allemaal op te halen met één enkele key. De rest van deze pagina behandelt de per-project data API.

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

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

Request formaat

De API gebruikt JSON-RPC 2.0. Elk 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 een willekeurig nummer of string zijn. Het wordt teruggekaatst in de response. Er zijn drie tools: get_metrics, get_timeseries en get_histogram.

get_metrics: huidige performance

Retourneert de huidige Core Web Vitals waarden met good/improve/poor beoordelingen. Dit is de tool die je gebruikt voor "wat is mijn LCP op dit moment?" type 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 beoordeling valt. Dit is vaak nuttiger dan alleen de p75 waarde. Een LCP van 2450ms met 61% good betekent dat de meeste gebruikers een prima ervaring hebben, maar de tail trekt de p75 naar beneden.

Voorbeeld: vergelijk mobiele vs desktop LCP

Gebruik de group parameter om resultaten op te splitsen naar een willekeurige dimensie. Dit is hoe je erachter komt 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 aggregaat zou 2500ms laten zien en je zou denken "niet geweldig, maar niet verschrikkelijk". De gegroepeerde weergave toont het echte verhaal: desktop is prima, mobiel heeft werk nodig.

Voorbeeld: filter naar een specifieke pagina op mobiel

Combineer filters om precies het verkeer te beperken 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

Retourneert metric waarden gebucketed over tijd met automatische trenddetectie. Dit is de tool die je gebruikt voor "is mijn LCP slechter geworden?" en "heeft die deploy de regressie opgelost?"

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. Trendwaarden 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 de datapunten niet zelf te parsen om te weten of dingen slechter worden.

get_histogram: distributievorm

Retourneert de distributie van een enkele metric als ~40 buckets met tellingen 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 neemt dit een enkele metric (niet 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 is en een brok traag 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 op je pagina's. Groepeer op inpel om de interacties te vinden die de slechtste INP produceren.

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 Core Web Vitals ranking. Als 75% van je page loads onder de drempelwaarde zit, slaag je.

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 andere), kun je deze direct verbinden. 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 echte gebruikersdata op, opent je site in Chrome en traceert de exacte oorzaak van een trage metric. De API verzorgt het "wat gebeurt er in productie" gedeelte, Chrome verzorgt 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 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 in het trial plan is ruim voldoende voor handmatige verkenning en AI assisted 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 reset om middernacht UTC of upgrade je plan.