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

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

CoreDash collecte les Core Web Vitals 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, JSON en entrée, JSON en sortie.

Le cas d'usage 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 interroger directement vos données d'utilisateurs réels. Demandez à votre IA « pourquoi mon LCP est-il lent sur mobile ? » et elle récupère les field data réelles pour répondre.

Nous avons développé CWV Superpowers sur cette base. C'est un agent IA qui combine vos field data 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 gérez une agence ou plusieurs projets depuis un seul compte ? Il existe une Agency API distincte. Elle utilise une clé maîtresse pour créer, mettre à jour et supprimer des projets, ainsi que pour récupérer les données de tous les projets avec une seule clé. Le reste de cette page concerne l'API de données par projet.

Authentification

Chaque requête nécessite une clé 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 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 depuis cette même page.

Format des requêtes

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

get_metrics : performance actuelle

Renvoie les valeurs actuelles des Core Web Vitals avec les évaluations good/improve/poor. C'est l'outil à utiliser 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 se trouvent sous forme de chaîne JSON dans le champ text. Une fois 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 le pourcentage de chargements de pages réels qui tombent dans chaque évaluation. C'est souvent plus utile que la seule valeur p75. Un LCP de 2450 ms avec 61 % de « good » signifie que la plupart des utilisateurs ont une bonne expérience, mais que la traîne tire la valeur p75 vers le bas.

Exemple : comparer le LCP mobile et desktop

Utilisez le paramètre group pour séparer les résultats selon n'importe quelle dimension. C'est ainsi que vous déterminez si votre problème de LCP concerne le 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 }
        }
      }
    }
  ]
}

Le mobile est à 3200 ms, le desktop à 1800 ms. L'agrégat afficherait 2500 ms, vous laissant penser « pas terrible, mais pas catastrophique ». La vue groupée révèle la réalité : le desktop est correct, le mobile doit être amélioré.

Exemple : filtrer sur une page spécifique sur mobile

Combinez les filters pour cibler précisément 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 : performance au fil du temps

Renvoie les valeurs des métriques regroupées par intervalles de temps avec une détection automatique des tendances. C'est l'outil à utiliser pour répondre aux questions comme « mon LCP s'est-il dégradé ? » ou « 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 résumé (summary) compare la seconde moitié de la période à la première moitié. Les valeurs de tendance sont improving (amélioration de plus de 5 %), stable (variation de moins de 5 %) ou regressing (régression de plus de 5 %). C'est ce qui rend le point de terminaison timeseries utile pour le monitoring automatisé : vous n'avez pas besoin d'analyser vous-même chaque point de données pour savoir si la situation se dégrade.

get_histogram : forme de la distribution

Renvoie la distribution d'une seule métrique sous forme d'environ 40 buckets avec le nombre de chargements de page par tranche. C'est l'outil à utiliser lorsque le p75 semble correct mais que vous soupçonnez une longue traîne, ou lorsque vous souhaitez visualiser la forme complète de vos données de performance.

Paramètres

Remarque : contrairement à get_metrics, cet outil prend une seule 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 bucket a des limites from/to, un count (le nombre estimé de chargements de page dans cette tranche) et un rating basé sur la position du bucket par rapport aux seuils des Core Web Vitals. Le dernier bucket a la valeur to: null car il représente la traîne ouverte.

La largeur des buckets est fixe par métrique : le LCP utilise 250 ms, l'INP utilise 25 ms, le CLS utilise 0,025, le FCP utilise 200 ms et le TTFB utilise 125 ms.

C'est utile pour comprendre la structure de vos données. Un p75 de 2400 ms peut signifier que la majorité des utilisateurs se situent autour de 2400 ms, ou que 60 % sont sous la barre des 1000 ms et qu'une part de trafic mobile lent étire la traîne. L'histogramme vous permet de savoir ce qu'il en est.

Dimensions

Utilisez ces clés dans filters ou comme valeur de group. Le filtrage restreint les données à un segment spécifique. Le groupement sépare les résultats pour vous permettre de 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 déclenchent le LCP sur vos pages. Groupez par inpel pour identifier les interactions qui génèrent 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 percentile 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 se situent sous le seuil, vous réussissez le test.

Utiliser l'API comme 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 aux outils get_metrics, get_timeseries et get_histogram, et peut interroger vos field data dans le cadre de n'importe quelle conversation.

C'est ainsi que fonctionne CWV Superpowers : il se connecte à CoreDash via MCP, récupère vos données d'utilisateurs réels, ouvre votre site dans Chrome et identifie 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 passe-t-il ».

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é API, et votre IA pourra répondre à des questions comme « quelles pages ont le pire INP sur mobile ? » en utilisant des field data réelles au lieu de deviner.

Limites de requêtes

Les limites s'appliquent par projet et par jour, et se réinitialisent à minuit UTC.

150 requêtes avec le forfait d'essai sont largement suffisantes pour l'exploration manuelle et le débogage assisté par IA. Si vous exécutez un monitoring automatisé dans la CI, les forfaits payants vous en offrent 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 votre forfait à niveau.