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

Seus dados de performance, onde quer que você precise

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

O caso de uso mais interessante: conectar a sua IA. A API do CoreDash usa 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 seus dados de campo do 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.

Administra uma agência ou gerencia muitos projetos a partir de uma única conta? Existe uma Agency API separada que usa uma chave mestre para criar, atualizar e excluir projetos, e para extrair dados de todos eles com uma única chave. O restante desta página cobre a API de dados por projeto.

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, em seguida, 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 escopo para um único projeto. Você pode criar várias chaves e revogá-las na mesma página.

Formato da requisição

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

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

O corpo da requisição é semelhante a este:

{
  "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. Esta é a ferramenta que você usa 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. Analisado, fica 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 de 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 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 mobile vs desktop

Use 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:

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

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

Combine 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 valores de métricas agrupados ao longo do tempo com detecção automática de tendências. Esta é a ferramenta que você usa 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:

{
  "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 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 útil para monitoramento automatizado: você não precisa analisar os pontos de dados por conta própria para saber se as coisas estão piorando.

get_histogram: forma da distribuição

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

Parâmetros

Nota: diferente do get_metrics, este requer 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:

{
  "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, um count de carregamentos de página estimados nessa faixa e um rating com base em onde o bucket se encontra em relação aos limites de 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 usa 250ms, INP usa 25ms, CLS usa 0.025, FCP usa 200ms, TTFB usa 125ms.

Isso é útil para entender a forma dos seus dados. Um p75 de 2400ms pode significar que a maioria dos usuários está em torno de 2400ms, ou pode significar que 60% estão abaixo de 1000ms e uma parte do tráfego mobile lento está puxando a cauda. O histograma informa qual é o caso.

Dimensões

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

Geral

Dispositivo e rede

Atribuição de métrica

Essas dimensões dizem 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 usa para o ranqueamento de Core Web Vitals. Se 75% dos carregamentos da sua página estiverem abaixo do limite, você é aprovado.

Usando a API como um servidor MCP

O endpoint da API é um servidor MCP totalmente compatível. Se a sua ferramenta de IA suportar MCP (Claude Code, Cursor, Windsurf e outros), 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 os dados dos seus usuários reais, abre seu site no Chrome e rastreia a causa exata de uma métrica lenta. A API fornece a parte "o que está acontecendo em produção", o Chrome fornece a parte "por que está acontecendo".

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

Limites de taxa

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 assistida 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 sua chave começa com cdk_ e se você não a revogou. Se receber -32002, você atingiu o limite diário. Aguarde a redefinição à meia-noite UTC ou faça o upgrade do seu plano.