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

I tuoi dati sulle 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. Due endpoint, 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 da mobile?" e questa estrarrà i dati sul campo effettivi per rispondere.

Abbiamo creato 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 rende tutto questo 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 a 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. Viene 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 è simile a questo:

{
  "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 due strumenti: get_metrics e get_timeseries.

get_metrics: performance attuale

Restituisce i valori attuali dei Core Web Vitals con valutazioni good/improve/poor. Questo è lo strumento che utilizzi 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 incapsula tutto nel formato JSON-RPC. 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 indica quale percentuale dei caricamenti di pagina reali rientra in ciascuna valutazione. Spesso è più utile del solo valore p75. Un LCP di 2450ms con il 61% good significa che la maggior parte degli utenti ha una buona esperienza, ma la coda della distribuzione sta trascinando in basso il p75.

Esempio: confronta LCP su mobile vs desktop

Usa il parametro group per dividere i risultati in base a qualsiasi dimensione. In questo modo puoi scoprire 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. Il dato aggregato mostrerebbe 2500ms e potresti pensare "non eccezionale, ma nemmeno terribile". La visualizzazione raggruppata mostra la vera situazione: il desktop va bene, il mobile richiede lavoro.

Esempio: filtra per una pagina specifica su mobile

Combina i 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 del trend. Questo è lo strumento che utilizzi per domande come "il mio LCP è peggiorato?" e "quel deploy ha risolto la regressione?".

Parametri

Esempio: trend del 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 del trend sono improving (miglioramento superiore al 5%), stable (entro il 5%) o regressing (peggioramento superiore al 5%). Questo è ciò che rende l'endpoint delle serie temporali utile per il monitoraggio automatizzato: non hai bisogno di analizzare i singoli punti dati per sapere se la situazione sta peggiorando.

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 permetterti di confrontare i segmenti fianco a fianco.

Generale

Dispositivo e rete

Attribuzione delle metriche

Queste dimensioni ti indicano cosa ha causato il valore di una metrica. Raggruppa per lcpel per vedere quali elementi diventano il LCP nelle 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 alle metriche

Il percentile predefinito è p75. Questo è ciò che utilizza Google per il posizionamento dei Core Web Vitals. Se il 75% dei caricamenti di pagina si trova al di sotto della soglia, lo superi.

Utilizzo dell'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 avrà quindi accesso a get_metrics e get_timeseries come strumenti e potrà 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 sul "cosa sta succedendo in produzione", Chrome fornisce la parte sul "perché sta succedendo".

Puoi anche connettere il server MCP alla tua configurazione IA. 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 del tipo "quali pagine hanno il peggior INP su mobile?" utilizzando dati reali sul campo invece di tirare a indovinare.

Limiti di frequenza (Rate limit)

I limiti sono 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 esegui 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 ricevi -32001, verifica che la tua chiave inizi con cdk_ e di non averla revocata. Se ricevi -32002, hai raggiunto il limite giornaliero. Attendi l'azzeramento di mezzanotte UTC o aggiorna il tuo piano.