API do CoreDash: Consulte Dados de Core Web Vitals de Usuários Reais

Seus dados de performance, em qualquer lugar que você precisar

O CoreDash coleta os Core Web Vitals de usuários reais que visitam seu site. A API dá acesso a esses mesmos dados a partir de qualquer ferramenta, script ou agente de IA. Três ferramentas, JSON entra, JSON sai.

O caso de uso mais interessante: conectar a sua IA. A API do CoreDash utiliza o mesmo protocolo que o Model Context Protocol (MCP), o que significa que ferramentas de IA como Claude, Cursor e Windsurf podem consultar seus dados de usuários reais diretamente. Pergunte à sua IA "por que meu LCP está lento no mobile?" e ela extrai os dados reais de campo para responder.

Nós construímos o CWV Superpowers sobre isso. É um agente de IA que combina os dados de campo do seu CoreDash com o Chrome DevTools para diagnosticar e corrigir problemas de Core Web Vitals. A API é o que torna isso possível.

Mas você não precisa de um agente de IA. Um comando curl funciona perfeitamente bem.

Autenticação

Toda requisição precisa de uma chave de API no cabeçalho Authorization:

Authorization: Bearer cdk_YOUR_API_KEY

Para obter uma chave:

1. Faça login em app.coredash.app
2. Vá para o seu projeto, depois em AI Insights, e então em Connect Your AI
3. Clique em Create API Key e copie-a. Ela é exibida apenas uma vez.

As chaves começam com cdk_ e têm o escopo de um único projeto. Você pode criar múltiplas chaves e revogá-las na mesma página.

Formato da requisição

A API utiliza JSON-RPC 2.0. Toda requisição é um POST para:

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

O corpo da requisição é assim:

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

O campo id pode ser qualquer número ou string. Ele é retornado na resposta. Existem três ferramentas: get_metrics, get_timeseries e get_histogram.

get_metrics: performance atual

Retorna os valores atuais de Core Web Vitals com classificações good/improve/poor (bom/precisa melhorar/ruim). Esta é a ferramenta que você utiliza para perguntas do tipo "qual é o meu LCP agora?".

Parâmetros

Exemplo: obter todas as métricas

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

A resposta bruta é um wrapper JSON-RPC:

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

Os dados reais são uma string JSON dentro do campo text. Analisados (parsed), ficam assim:

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

O objeto distribution informa qual porcentagem dos carregamentos de página reais se enquadra em cada classificação. Isso geralmente é mais útil do que apenas o valor do p75 sozinho. Um LCP de 2450ms com 61% "good" (bom) significa que a maioria dos usuários tem uma boa experiência, mas a cauda longa está puxando o p75 para baixo.

Exemplo: comparar o LCP de mobile vs desktop

Utilize o parâmetro group para dividir os resultados por qualquer dimensão. É assim que você descobre se o seu problema de LCP é um problema no 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"
      }
    }
  }'

Resposta analisada (parsed):

{
  "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 em 3200ms, desktop em 1800ms. O agregado mostraria 2500ms e você pensaria "não está ótimo, mas não é terrível". A visualização agrupada mostra a verdadeira história: o desktop está bem, o mobile precisa de melhorias.

Exemplo: filtrar para uma página específica no mobile

Combine os filters para restringir exatamente ao tráfego que importa para você:

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 ao longo do tempo

Retorna os valores da métrica agrupados (bucketed) ao longo do tempo com detecção automática de tendências. Esta é a ferramenta que você utiliza para "meu LCP piorou?" e "aquele deploy corrigiu a regressão?".

Parâmetros

Exemplo: tendência do LCP nos últimos 7 dias

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

Resposta analisada (parsed):

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

O summary compara a segunda metade do período com a primeira metade. Os valores de tendência (trend) são improving (mais de 5% melhor), stable (dentro de 5%) ou regressing (mais de 5% pior). É isso que torna o endpoint de séries temporais (timeseries) útil para monitoramento automatizado: você não precisa analisar os pontos de dados (data points) sozinho para saber se as coisas estão piorando.

get_histogram: formato da distribuição

Retorna a distribuição de uma única métrica em ~40 buckets com contagens por faixa. Esta é a ferramenta que você utiliza quando o p75 parece bom, mas você suspeita de uma cauda longa, ou quando deseja ver o formato completo dos seus dados de performance.

Parâmetros

Nota: ao contrário de get_metrics, este aceita apenas uma única metric (não metrics). Uma métrica por requisição.

Exemplo: distribuição do LCP no 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"
      }
    }
  }'

Resposta analisada (parsed):

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

Cada bucket possui limites from/to (de/para), um count (contagem) de carregamentos de página estimados nessa faixa, e um rating (classificação) baseado na posição do bucket em relação aos limites dos Core Web Vitals. O último bucket possui to: null porque é a cauda com final aberto.

As larguras dos buckets são fixas por métrica: LCP utiliza 250ms, INP utiliza 25ms, CLS utiliza 0.025, FCP utiliza 200ms, TTFB utiliza 125ms.

Isso é útil para entender o formato dos seus dados. Um p75 de 2400ms poderia significar que a maioria dos usuários está perto de 2400ms, ou poderia significar que 60% estão abaixo de 1000ms e uma parte de tráfego lento no mobile está puxando a cauda. O histograma informa qual é a situação.

Dimensões

Utilize estas chaves em filters ou como valor de group. A filtragem restringe os dados a um segmento específico. O agrupamento divide os resultados para que você possa comparar segmentos lado a lado.

Geral

Dispositivo e rede

Atribuição de métricas

Essas dimensões informam o que causou um valor de métrica. Agrupe por lcpel para ver quais elementos se tornam o LCP em suas páginas. Agrupe por inpel para encontrar as interações que produzem o pior INP.

Exemplos de filtros

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

Referência de métricas

O percentil padrão é o p75. É isso que o Google utiliza para o ranqueamento dos Core Web Vitals. Se 75% dos carregamentos da sua página estiverem abaixo do limite, você passa.

Utilizando a API como um servidor MCP

O endpoint da API é um servidor MCP totalmente compatível. Se a sua ferramenta de IA suporta MCP (Claude Code, Cursor, Windsurf e outras), você pode conectá-la diretamente. A IA então tem acesso a get_metrics, get_timeseries e get_histogram como ferramentas e pode consultar seus dados de campo como parte de qualquer conversa.

É assim que o CWV Superpowers funciona: ele se conecta ao CoreDash via MCP, extrai seus dados de usuários reais, abre seu site no Chrome e rastreia a causa exata de uma métrica lenta. A API fornece a parte de "o que está acontecendo em produção", e o Chrome fornece a parte de "por que isso está acontecendo".

Você também pode conectar o servidor MCP ao seu próprio setup de IA. Aponte o seu cliente MCP para https://app.coredash.app/api/mcp com a sua chave de API, e a sua IA poderá responder a perguntas como "quais páginas têm o pior INP no mobile?" utilizando dados reais de campo em vez de adivinhar.

Limites de taxa (Rate limits)

Os limites são por projeto por dia e são redefinidos à meia-noite UTC.

150 requisições no plano trial são suficientes para exploração manual e depuração auxiliada por IA. Se você estiver executando monitoramento automatizado em CI, os planos pagos oferecem 500 por dia.

Tratamento de erros

Os erros retornam como objetos de erro JSON-RPC:

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

Se você receber -32001, verifique se a sua chave começa com cdk_ e se você não a revogou. Se você receber -32002, você atingiu o limite diário. Aguarde a redefinição à meia-noite UTC ou faça o upgrade do seu plano.