API do CoreDash: consulte dados de Core Web Vitals de usuários reais

Seus dados de performance, onde você precisar

O CoreDash coleta 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, entra JSON, sai JSON.

O caso de uso mais interessante: conectar sua IA. A API do CoreDash usa o mesmo protocolo do 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 puxa os field data reais para responder.

Criamos o CWV Superpowers sobre isso. Ele é um agente de IA que combina seus field data 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 tão bem quanto.

Gerencia uma agência ou muitos projetos a partir de uma única conta? Existe uma Agency API separada que usa uma chave mestre para criar, atualizar e excluir projetos, além de 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. Acesse seu projeto, depois AI Insights, e então Connect Your AI
3. Clique em Create API Key e copie-a. Ela é exibida apenas uma vez.

As chaves começam com cdk_ e são restritas a 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 é 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 do Core Web Vitals com as avaliaçõ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. Após o parse, 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 mostra qual porcentagem dos carregamentos de página reais cai em cada avaliação. Isso costuma ser mais útil do que apenas o valor do p75. Um LCP de 2450ms com 61% de "good" significa que a maioria dos usuários tem uma boa experiência, mas a cauda está arrastando o p75 para baixo.

Exemplo: comparar LCP no 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 é específico do 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 após o parse:

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

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

Combine filters para restringir a análise exatamente ao tráfego que importa:

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 das métricas agrupados ao longo do tempo com detecção automática de tendência. Esta é a ferramenta que você usa para perguntas como "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 após o parse:

{
  "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% de variação) ou regressing (mais de 5% pior). É isso que torna o endpoint de timeseries ú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: formato da distribuição

Retorna a distribuição de uma única métrica em cerca de 40 buckets com contagens por intervalo. Esta é a ferramenta que você usa 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 do get_metrics, este aceita 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 após o parse:

{
  "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, uma contagem (count) de carregamentos de página estimados nesse intervalo e uma classificação (rating) baseada em onde o bucket fica em relação aos limites do Core Web Vitals. O último bucket tem to: null porque representa a cauda aberta.

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

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

Dimensões

Use essas chaves em filters ou como o valor de 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étricas

Estas dimensões informam o que causou o valor de uma 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 geram o pior INP.

Exemplos de filtros

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

Referência das métricas

O percentil padrão é o p75. Este é o valor que o Google usa para o ranking do Core Web Vitals. Se 75% dos carregamentos de página estiverem abaixo do limite, você passa.

Usando a API como um servidor MCP

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

É assim que o CWV Superpowers funciona: ele se conecta ao CoreDash via MCP, puxa 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 do "o que está acontecendo em produção", enquanto o Chrome cuida do "por que está acontecendo".

Você também pode conectar o servidor MCP ao seu próprio setup de IA. Basta apontar 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 field data reais em vez de adivinhar.

Rate limits

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

150 requisições no plano Trial são mais do que suficientes para exploração manual e depuração assistida por IA. Se você roda monitoramento automatizado em CI, os planos pagos oferecem 500 requisições 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 não foi revogada. Se receber -32002, você atingiu o limite diário. Aguarde o reset da meia-noite UTC ou faça o upgrade do seu plano.