API CoreDash : Interrogez les données Core Web Vitals de vos utilisateurs réels

Vos données de performances, partout où vous en avez besoin

CoreDash collecte les Core Web Vitals auprès des utilisateurs réels qui visitent votre site. L'API vous donne accès à ces mêmes données depuis n'importe quel outil, script ou agent IA. Trois outils, entrée JSON, sortie JSON.

Le cas d'utilisation le plus intéressant : connecter votre IA. L'API CoreDash utilise le même protocole que le Model Context Protocol (MCP), ce qui signifie que des outils d'IA comme Claude, Cursor et Windsurf peuvent interroger directement les données de vos utilisateurs réels. Demandez à votre IA "pourquoi mon LCP est-il lent sur mobile ?" et elle récupérera les données de terrain réelles pour vous répondre.

Nous avons conçu CWV Superpowers sur cette base. Il s'agit d'un agent IA qui combine vos données de terrain CoreDash avec les Chrome DevTools pour diagnostiquer et corriger les problèmes de Core Web Vitals. C'est l'API qui rend cela possible.

Mais vous n'avez pas besoin d'un agent IA. Une commande curl fonctionne tout aussi bien.

Authentification

Chaque requête nécessite une clé d'API dans l'en-tête Authorization :

Authorization: Bearer cdk_YOUR_API_KEY

Pour obtenir une clé :

1. Connectez-vous sur app.coredash.app
2. Allez sur votre projet, puis dans AI Insights, puis Connect Your AI
3. Cliquez sur Create API Key et copiez-la. Elle ne s'affichera qu'une seule fois.

Les clés commencent par cdk_ et sont limitées à un seul projet. Vous pouvez créer plusieurs clés et les révoquer depuis la même page.

Format de la requête

L'API utilise JSON-RPC 2.0. Chaque requête est une requête POST vers :

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

Le corps de la requête ressemble à ceci :

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

Le champ id peut être n'importe quel nombre ou chaîne de caractères. Il est renvoyé en écho dans la réponse. Il existe trois outils : get_metrics, get_timeseries et get_histogram.

get_metrics : performances actuelles

Renvoie les valeurs actuelles des Core Web Vitals avec les évaluations good/improve/poor. C'est l'outil que vous utilisez pour les questions du type "quel est mon LCP en ce moment ?".

Paramètres

Exemple : obtenir toutes les métriques

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

La réponse brute est une enveloppe JSON-RPC :

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

Les données réelles se présentent sous la forme d'une chaîne JSON dans le champ text. Une fois analysée, elle ressemble à ceci :

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

L'objet distribution vous indique quel pourcentage de chargements de pages réels tombe dans chaque évaluation. C'est souvent plus utile que la seule valeur p75. Un LCP de 2450 ms avec 61 % de good (bon) signifie que la plupart des utilisateurs bénéficient d'une bonne expérience, mais la traîne fait chuter le p75.

Exemple : comparer le LCP sur mobile et sur desktop

Utilisez le paramètre group pour fractionner les résultats par n'importe quelle dimension. C'est ainsi que vous déterminez si votre problème de LCP est lié au mobile :

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

Réponse analysée :

{
  "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 à 3200 ms, desktop à 1800 ms. L'agrégation indiquerait 2500 ms et vous penseriez "pas terrible, mais pas catastrophique". La vue groupée montre la réalité : le desktop va bien, le mobile nécessite du travail.

Exemple : filtrer pour une page spécifique sur mobile

Combinez filters pour restreindre exactement le trafic qui vous intéresse :

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 : les performances dans le temps

Renvoie les valeurs des métriques regroupées au fil du temps avec une détection automatique des tendances. C'est l'outil que vous utilisez pour savoir "mon LCP s'est-il aggravé ?" ou "ce déploiement a-t-il corrigé la régression ?".

Paramètres

Exemple : Tendance LCP sur les 7 derniers jours

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

Réponse analysée :

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

L'objet summary compare la seconde moitié de la période à la première. Les valeurs de tendance sont improving (meilleur de plus de 5 %), stable (à 5 % près) ou regressing (pire de plus de 5 %). C'est ce qui rend le point de terminaison timeseries utile pour la surveillance automatisée : vous n'avez pas besoin d'analyser vous-même les points de données pour savoir si la situation se dégrade.

get_histogram : forme de la distribution

Renvoie la distribution d'une métrique unique sous la forme d'environ 40 intervalles avec le nombre d'occurrences par plage. C'est l'outil que vous utilisez lorsque le p75 semble correct mais que vous soupçonnez une longue traîne, ou lorsque vous souhaitez voir la forme complète de vos données de performances.

Paramètres

Note : contrairement à get_metrics, cet outil prend un seul metric (et non metrics). Une seule métrique par requête.

Exemple : Distribution LCP sur mobile

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

Réponse analysée :

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

Chaque intervalle a des limites from/to, un count de chargements de pages estimés dans cette plage, et un rating basé sur la position de l'intervalle par rapport aux seuils des Core Web Vitals. Le dernier intervalle a to: null car il s'agit d'une traîne ouverte.

Les largeurs des intervalles sont fixes par métrique : LCP utilise 250 ms, INP utilise 25 ms, CLS utilise 0.025, FCP utilise 200 ms, TTFB utilise 125 ms.

Ceci est utile pour comprendre la forme de vos données. Un p75 de 2400 ms pourrait signifier que la plupart des utilisateurs se situent autour de 2400 ms, ou cela pourrait signifier que 60 % sont en dessous de 1000 ms et qu'une part importante de trafic mobile lent allonge la traîne. L'histogramme vous indique de quoi il s'agit.

Dimensions

Utilisez ces clés dans filters ou en tant que valeur group. Le filtrage restreint les données à un segment spécifique. Le regroupement fractionne les résultats afin que vous puissiez comparer les segments côte à côte.

Général

Appareil et réseau

Attribution des métriques

Ces dimensions vous indiquent ce qui a causé la valeur d'une métrique. Regroupez par lcpel pour voir quels éléments deviennent le LCP sur vos pages. Regroupez par inpel pour trouver les interactions qui produisent le pire INP.

Exemples de filtres

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

Référence des métriques

Le centile par défaut est le p75. C'est ce que Google utilise pour le classement des Core Web Vitals. Si 75 % des chargements de vos pages sont inférieurs au seuil, vous réussissez.

Utiliser l'API en tant que serveur MCP

Le point de terminaison de l'API est un serveur MCP entièrement compatible. Si votre outil d'IA prend en charge le MCP (Claude Code, Cursor, Windsurf et autres), vous pouvez le connecter directement. L'IA a alors accès à get_metrics, get_timeseries et get_histogram en tant qu'outils et peut interroger vos données de terrain dans le cadre de n'importe quelle conversation.

C'est ainsi que fonctionne CWV Superpowers : il se connecte à CoreDash via MCP, extrait les données de vos utilisateurs réels, ouvre votre site dans Chrome et trace la cause exacte d'une métrique lente. L'API fournit la partie "ce qui se passe en production", Chrome fournit la partie "pourquoi cela se produit".

Vous pouvez également connecter le serveur MCP à votre propre configuration d'IA. Pointez votre client MCP vers https://app.coredash.app/api/mcp avec votre clé d'API, et votre IA pourra répondre à des questions telles que "quelles pages ont le pire INP sur mobile ?" en utilisant de véritables données de terrain au lieu de deviner.

Limites de taux

Les limites sont définies par projet et par jour et se réinitialisent à minuit UTC.

150 requêtes sur le forfait d'essai suffisent amplement pour l'exploration manuelle et le débogage assisté par IA. Si vous exécutez une surveillance automatisée dans l'intégration continue (CI), les forfaits payants vous en donnent 500 par jour.

Gestion des erreurs

Les erreurs sont renvoyées sous forme d'objets d'erreur JSON-RPC :

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

Si vous obtenez -32001, vérifiez que votre clé commence par cdk_ et que vous ne l'avez pas révoquée. Si vous obtenez -32002, vous avez atteint la limite quotidienne. Attendez la réinitialisation de minuit UTC ou mettez à niveau votre forfait.