API CoreDash: Interroga i dati Core Web Vitals degli utenti reali

I tuoi dati di performance, ovunque tu ne abbia bisogno

CoreDash raccoglie i Core Web Vitals dagli utenti reali che visitano il tuo sito. L'API ti dà accesso a quegli stessi dati da qualsiasi strumento, script o agente IA. Tre strumenti, JSON in ingresso, JSON in uscita.

Il caso d'uso più interessante: connettere la tua IA. L'API CoreDash utilizza lo stesso protocollo del Model Context Protocol (MCP), il che significa che strumenti IA come Claude, Cursor e Windsurf possono interrogare direttamente i dati dei tuoi utenti reali. Chiedi alla tua IA "perché il mio LCP è lento su mobile?" e otterrà i dati reali sul campo per rispondere.

Abbiamo costruito CWV Superpowers su questa base. È un agente IA che combina i dati sul campo di CoreDash con i Chrome DevTools per diagnosticare e risolvere i problemi dei Core Web Vitals. L'API è ciò che lo rende possibile.

Ma non hai bisogno di un agente IA. Un comando curl funziona altrettanto bene.

Autenticazione

Ogni richiesta necessita di una chiave API nell'header Authorization:

Authorization: Bearer cdk_YOUR_API_KEY

Per ottenere una chiave:

1. Accedi su app.coredash.app
2. Vai al tuo progetto, poi su AI Insights, quindi Connect Your AI
3. Clicca su Create API Key e copiala. Verrà mostrata una sola volta.

Le chiavi iniziano con cdk_ e sono limitate a un singolo progetto. Puoi creare chiavi multiple e revocarle dalla stessa pagina.

Formato della richiesta

L'API utilizza JSON-RPC 2.0. Ogni richiesta è una POST a:

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

Il corpo della richiesta si presenta così:

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

Il campo id può essere qualsiasi numero o stringa. Viene restituito nella risposta. Ci sono tre strumenti: get_metrics, get_timeseries e get_histogram.

get_metrics: performance attuale

Restituisce i valori attuali dei Core Web Vitals con le valutazioni good/improve/poor. Questo è lo strumento da utilizzare per domande del tipo "qual è il mio LCP in questo momento?".

Parametri

Esempio: ottieni tutte le metriche

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 risposta grezza è un wrapper JSON-RPC:

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

I dati effettivi sono una stringa JSON all'interno del campo text. Analizzati, si presentano così:

{
  "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'oggetto distribution ti dice quale percentuale di caricamenti reali della pagina rientra in ciascuna valutazione. Questo è spesso più utile del solo valore p75. Un LCP di 2450ms con il 61% di good significa che la maggior parte degli utenti ha una buona esperienza, ma la coda sta trascinando verso il basso il p75.

Esempio: confronta LCP tra mobile e desktop

Usa il parametro group per dividere i risultati per qualsiasi dimensione. È così che scopri se il tuo problema di LCP è un problema legato al 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"
      }
    }
  }'

Risposta analizzata:

{
  "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 a 3200ms, desktop a 1800ms. L'aggregato mostrerebbe 2500ms e penseresti "non eccezionale, ma neanche terribile". La vista raggruppata mostra la vera storia: il desktop va bene, il mobile ha bisogno di lavoro.

Esempio: filtra per una pagina specifica su mobile

Combina filters per restringere esattamente al traffico che ti interessa:

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 nel tempo

Restituisce i valori delle metriche raggruppati nel tempo con rilevamento automatico delle tendenze. Questo è lo strumento che usi per domande come "il mio LCP è peggiorato?" e "quel deploy ha risolto la regressione?".

Parametri

Esempio: tendenza LCP negli ultimi 7 giorni

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

Risposta analizzata:

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

Il summary confronta la seconda metà del periodo con la prima metà. I valori della tendenza (trend) sono improving (miglioramento di oltre il 5%), stable (entro il 5%), o regressing (peggioramento di oltre il 5%). Questo è ciò che rende l'endpoint delle serie temporali utile per il monitoraggio automatizzato: non hai bisogno di analizzare i punti dati da solo per sapere se le cose stanno peggiorando.

get_histogram: forma della distribuzione

Restituisce la distribuzione di una singola metrica in circa 40 gruppi (bucket) con i conteggi per intervallo. Questo è lo strumento da usare quando il p75 sembra buono ma sospetti una coda lunga, o quando vuoi vedere la forma completa dei tuoi dati di performance.

Parametri

Nota: a differenza di get_metrics, questo accetta una singola metric (non metrics). Una metrica per richiesta.

Esempio: distribuzione LCP su 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"
      }
    }
  }'

Risposta analizzata:

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

Ogni bucket ha limiti from/to, un count di caricamenti stimati della pagina in quell'intervallo, e un rating basato su dove si posiziona il bucket rispetto alle soglie dei Core Web Vitals. L'ultimo bucket ha to: null perché rappresenta la coda aperta.

Le larghezze dei bucket sono fisse per metrica: l'LCP usa 250ms, l'INP usa 25ms, il CLS usa 0.025, l'FCP usa 200ms, il TTFB usa 125ms.

Questo è utile per capire la forma dei tuoi dati. Un p75 di 2400ms potrebbe significare che la maggior parte degli utenti si aggira intorno a 2400ms, oppure potrebbe significare che il 60% è sotto i 1000ms e una porzione di traffico mobile lento sta allungando la coda. L'istogramma ti dice quale delle due opzioni è quella reale.

Dimensioni

Usa queste chiavi in filters o come valore di group. Il filtraggio restringe i dati a un segmento specifico. Il raggruppamento divide i risultati in modo da poter confrontare i segmenti fianco a fianco.

Generale

Dispositivo e rete

Attribuzione delle metriche

Queste dimensioni ti dicono cosa ha causato un valore metrico. Raggruppa per lcpel per vedere quali elementi diventano l'LCP attraverso le tue pagine. Raggruppa per inpel per trovare le interazioni che producono l'INP peggiore.

Esempi di filtri

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

Riferimento per le metriche

Il percentile predefinito è p75. Questo è ciò che Google utilizza per il ranking dei Core Web Vitals. Se il 75% dei caricamenti della tua pagina è al di sotto della soglia, passi il test.

Usare l'API come server MCP

L'endpoint dell'API è un server MCP completamente compatibile. Se il tuo strumento IA supporta MCP (Claude Code, Cursor, Windsurf e altri), puoi connetterlo direttamente. L'IA ha quindi accesso a get_metrics, get_timeseries e get_histogram come strumenti e può interrogare i tuoi dati sul campo come parte di qualsiasi conversazione.

Ecco come funziona CWV Superpowers: si connette a CoreDash tramite MCP, estrae i dati dei tuoi utenti reali, apre il tuo sito in Chrome e traccia la causa esatta di una metrica lenta. L'API fornisce la parte "cosa sta succedendo in produzione", Chrome fornisce la parte "perché sta succedendo".

Puoi anche connettere il server MCP alla tua configurazione IA personale. Punta il tuo client MCP su https://app.coredash.app/api/mcp con la tua chiave API, e la tua IA potrà rispondere a domande come "quali pagine hanno l'INP peggiore su mobile?" usando dati reali sul campo invece di tirare a indovinare.

Limiti di frequenza (Rate limits)

I limiti si intendono per progetto, al giorno, e si azzerano a mezzanotte UTC.

150 richieste nel piano di prova sono sufficienti per l'esplorazione manuale e il debug assistito dall'IA. Se stai eseguendo un monitoraggio automatizzato in CI, i piani a pagamento ti offrono 500 richieste al giorno.

Gestione degli errori

Gli errori vengono restituiti come oggetti di errore JSON-RPC:

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

Se ottieni -32001, controlla che la tua chiave inizi con cdk_ e che tu non l'abbia revocata. Se ottieni -32002, hai raggiunto il limite giornaliero. Attendi il reset a mezzanotte UTC o aggiorna il tuo piano.