API CoreDash : Requêter les données réelles des utilisateurs pour les Core Web Vitals

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

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

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 les outils d'IA comme Claude, Cursor et Windsurf peuvent requêter vos données d'utilisateurs réels directement. Demandez à votre IA "pourquoi mon LCP est lent sur mobile ?" et elle récupérera les véritables données de terrain pour y répondre.

Nous avons construit CWV Superpowers par-dessus cela. C'est un agent IA qui combine vos données de terrain CoreDash avec Chrome DevTools pour diagnostiquer et corriger les problèmes de Core Web Vitals. L'API est ce qui rend cela possible.

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

Vous dirigez une agence ou gérez de nombreux projets depuis un seul compte ? Il existe une Agency API distincte qui utilise une clé maître pour créer, mettre à jour et supprimer des projets, et pour extraire des données de tous les projets avec une seule clé. Le reste de cette page couvre l'API de données par projet.

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 dans votre projet, puis dans AI Insights, puis dans Connect Your AI
3. Cliquez sur Create API Key et copiez-la. Elle ne s'affiche 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 à partir de la même page.

Format de la requête

L'API utilise JSON-RPC 2.0. Chaque requête est un 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é dans la réponse. Il y a trois outils : get_metrics, get_timeseries et get_histogram.

get_metrics : performance actuelle

Retourne 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 un wrapper JSON-RPC :

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

Les données réelles sont une chaîne JSON à l'intérieur du champ text. Analysées, elles ressemblent à 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 des chargements de page réels correspond à chaque évaluation. C'est souvent plus utile que la valeur p75 seule. Un LCP de 2450 ms avec 61 % en good signifie que la plupart des utilisateurs ont une bonne expérience, mais que la traîne tire le p75 vers le bas.

Exemple : comparer le LCP mobile vs bureau

Utilisez le paramètre group pour diviser les résultats par n'importe quelle dimension. C'est ainsi que vous découvrez si votre problème de LCP est un problème 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": 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, bureau à 1800 ms. L'agrégat afficherait 2500 ms et vous penseriez "pas génial, mais pas terrible". La vue groupée montre la véritable histoire : le bureau est correct, le mobile nécessite du travail.

Exemple : filtrer vers une page spécifique sur mobile

Combinez filters pour vous limiter exactement au 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 : la performance dans le temps

Retourne les valeurs des métriques regroupées dans le temps avec une détection automatique des tendances. C'est l'outil que vous utilisez pour "mon LCP s'est-il détérioré ?" et "ce déploiement a-t-il corrigé la régression ?".

Paramètres

Exemple : tendance du 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"
    }
  }
}

Le summary (résumé) compare la deuxième moitié de la période à la première moitié. Les valeurs de tendance sont improving (en amélioration de plus de 5 %), stable (à moins de 5 %) ou regressing (en régression 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 les points de données vous-même pour savoir si les choses empirent.

get_histogram : forme de la distribution

Retourne la distribution d'une seule métrique sous forme de ~40 groupes avec le nombre 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 voulez voir la forme complète de vos données de performance.

Paramètres

Remarque : contrairement à get_metrics, ceci prend un seul metric (et non metrics). Une métrique par requête.

Exemple : distribution du 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 groupe a des limites from/to, un nombre (count) de chargements de page estimés dans cette plage, et une évaluation (rating) basée sur la position du groupe par rapport aux seuils des Core Web Vitals. Le dernier groupe a to: null car il s'agit d'une traîne ouverte.

Les largeurs de groupe sont fixes par métrique : le LCP utilise 250 ms, l'INP utilise 25 ms, le CLS utilise 0,025, le FCP utilise 200 ms, le TTFB utilise 125 ms.

Cela 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 partie du trafic mobile lent tire la traîne. L'histogramme vous indique lequel des deux c'est.

Dimensions

Utilisez ces clés dans filters ou comme valeur de group. Le filtrage limite les données à un segment spécifique. Le regroupement divise 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. Groupez par lcpel pour voir quels éléments deviennent le LCP sur vos pages. Groupez 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 p75. C'est ce que Google utilise pour le classement des Core Web Vitals. Si 75 % de vos chargements de page 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 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 requêter 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, récupère 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 comme "quelles pages ont le pire INP sur mobile ?" en utilisant de véritables données de terrain plutôt qu'en devinant.

Limites de taux

Les limites s'appliquent par projet et par jour, et sont réinitialisées à minuit UTC.

150 requêtes sur le plan d'essai sont amplement suffisantes pour l'exploration manuelle et le débogage assisté par l'IA. Si vous exécutez une surveillance automatisée en CI, les plans 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 plan.