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

I tuoi dati di performance, ovunque ti servano

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

Il caso d'uso più interessante: connettere la tua IA. L'API di 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?" ed essa estrarrà i dati effettivi 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 relativi ai Core Web Vitals. L'API è ciò che lo rende possibile.

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

Gestisci un'agenzia o molti progetti da un singolo account? Esiste una Agency API separata che utilizza una master key per creare, aggiornare e cancellare progetti, e per estrarre i dati da tutti loro con una singola chiave. Il resto di questa pagina tratta l'API dei dati per singolo progetto.

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 su 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 più chiavi 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 è il seguente:

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

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

get_metrics: performance attuali

Restituisce i valori attuali dei Core Web Vitals con 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. Una volta 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 pagina reali rientra in ciascuna valutazione. Questo è spesso più utile del solo valore p75. Un LCP di 2450ms con il 61% di valutazioni "good" significa che la maggior parte degli utenti ha una buona esperienza utente, ma la coda di caricamenti più lenti sta abbassando il p75.

Esempio: confronta LCP tra mobile e desktop

Usa il parametro group per dividere i risultati in base a qualsiasi dimensione. Questo è il modo in cui scopri se il tuo problema di LCP è un problema relativo 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 fantastico, ma non terribile". La vista raggruppata mostra la vera storia: desktop va bene, mobile ha bisogno di lavoro.

Esempio: filtra per una pagina specifica su mobile

Combina filters per restringere la ricerca 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 (bucketed) con rilevamento automatico del trend. Questo è lo strumento da utilizzare per "il mio LCP è peggiorato?" e "quel deploy ha risolto la regressione?".

Parametri

Esempio: trend dell'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 di 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 data point da solo per sapere se le cose stanno peggiorando.

get_histogram: forma della distribuzione

Restituisce la distribuzione di una singola metrica in ~40 bucket con conteggi per intervallo. Questo è lo strumento da utilizzare quando il p75 sembra buono ma sospetti una coda lunga, oppure 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 dell'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 dei caricamenti pagina stimati in quell'intervallo e una rating basata sulla posizione del bucket rispetto alle soglie dei Core Web Vitals. L'ultimo bucket ha to: null perché è la coda a tempo indeterminato.

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

Questo è utile per comprendere la forma dei tuoi dati. Un p75 di 2400ms potrebbe significare che la maggior parte degli utenti si aggira intorno ai 2400ms, oppure potrebbe significare che il 60% è al di sotto dei 1000ms e una porzione di traffico mobile lento sta trainando la coda. L'istogramma ti dice qual è il caso.

Dimensioni

Usa queste chiavi nei filters o come valore di group. Il filtraggio restringe i dati a un segmento specifico. Il raggruppamento divide i risultati per consentirti di confrontare i segmenti fianco a fianco.

Generale

Dispositivo e rete

Attribuzione delle metriche

Queste dimensioni ti dicono cosa ha causato il valore di una metrica. Raggruppa per lcpel per vedere quali elementi diventano l'LCP tra le tue pagine. Raggruppa per inpel per trovare le interazioni che producono il peggior INP.

Esempi di filtri

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

Riferimento per le metriche

Il percentile di default è 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 tool IA supporta MCP (Claude Code, Cursor, Windsurf e altri), puoi connetterlo direttamente. L'IA avrà quindi accesso a get_metrics, get_timeseries e get_histogram come strumenti e potrà interrogare i tuoi dati sul campo come parte di qualsiasi conversazione.

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

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

Limiti di rate

I limiti sono per progetto al giorno e si resettano a mezzanotte UTC.

150 richieste nel piano Trial sono sufficienti per l'esplorazione manuale e il debugging assistito dall'IA. Se esegui il 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 di mezzanotte UTC o fai l'upgrade del tuo piano.