API de CoreDash: Consulta Datos Reales de Core Web Vitals de Usuarios

Tus datos de rendimiento, en cualquier lugar que los necesites

CoreDash recopila Core Web Vitals de usuarios reales que visitan tu sitio. La API te da acceso a esos mismos datos desde cualquier herramienta, script o agente de IA. Tres herramientas, JSON de entrada, JSON de salida.

El caso de uso más interesante: conectar tu IA. La API de CoreDash utiliza el mismo protocolo que el Model Context Protocol (MCP), lo que significa que las herramientas de IA como Claude, Cursor y Windsurf pueden consultar tus datos de campo reales directamente. Pregúntale a tu IA "¿por qué mi LCP es lento en móvil?" y extraerá los datos de campo reales para responder.

Construimos CWV Superpowers sobre esto. Es un agente de IA que combina tus datos de campo de CoreDash con Chrome DevTools para diagnosticar y solucionar problemas de Core Web Vitals. La API es lo que hace que esto sea posible.

Pero no necesitas un agente de IA. Un comando curl funciona igual de bien.

¿Diriges una agencia o gestionas muchos proyectos desde una sola cuenta? Existe una Agency API separada que utiliza una clave maestra para crear, actualizar y eliminar proyectos, y para extraer datos de todos ellos con una sola clave. El resto de esta página cubre la API de datos por proyecto.

Autenticación

Cada petición necesita una clave de API en el encabezado Authorization:

Authorization: Bearer cdk_YOUR_API_KEY

Para obtener una clave:

1. Inicia sesión en app.coredash.app
2. Ve a tu proyecto, luego a AI Insights, luego a Connect Your AI
3. Haz clic en Create API Key y cópiala. Solo se muestra una vez.

Las claves comienzan con cdk_ y están limitadas a un solo proyecto. Puedes crear múltiples claves y revocarlas desde la misma página.

Formato de petición

La API utiliza JSON-RPC 2.0. Cada petición es un POST a:

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

El cuerpo de la petición se ve así:

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

El campo id puede ser cualquier número o cadena. Se devuelve en la respuesta. Hay tres herramientas: get_metrics, get_timeseries y get_histogram.

get_metrics: rendimiento actual

Devuelve los valores actuales de Core Web Vitals con calificaciones good/improve/poor. Esta es la herramienta que usas para preguntas del tipo "¿cuál es mi LCP en este momento?".

Parámetros

Ejemplo: obtener todas las 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": {}
    }
  }'

La respuesta cruda es un envoltorio JSON-RPC:

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

Los datos reales son una cadena JSON dentro del campo text. Analizada, se ve así:

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

El objeto distribution te indica qué porcentaje de cargas de página reales caen en cada calificación. Esto a menudo es más útil que el valor p75 por sí solo. Un LCP de 2450ms con un 61% bueno significa que la mayoría de los usuarios tienen una buena experiencia, pero la cola está arrastrando el p75 hacia abajo.

Ejemplo: comparar LCP en móvil vs escritorio

Usa el parámetro group para dividir los resultados por cualquier dimensión. Así es como descubres si tu problema de LCP es un problema en móvil:

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

Respuesta analizada:

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

Móvil a 3200ms, escritorio a 1800ms. El agregado mostraría 2500ms y pensarías "no está genial, pero tampoco es terrible". La vista agrupada muestra la historia real: el escritorio está bien, el móvil necesita trabajo.

Ejemplo: filtrar a una página específica en móvil

Combina filters para limitar exactamente al tráfico que te 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: rendimiento a lo largo del tiempo

Devuelve los valores de las métricas agrupados a lo largo del tiempo con detección automática de tendencias. Esta es la herramienta que usas para "¿ha empeorado mi LCP?" y "¿solucionó ese despliegue la regresión?".

Parámetros

Ejemplo: tendencia de LCP en los últimos 7 días

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

Respuesta analizada:

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

El summary compara la segunda mitad del período con la primera mitad. Los valores de tendencia son improving (más de un 5% mejor), stable (dentro del 5%), o regressing (más de un 5% peor). Esto es lo que hace útil al endpoint de series temporales para el monitoreo automatizado: no necesitas analizar los puntos de datos tú mismo para saber si las cosas están empeorando.

get_histogram: forma de la distribución

Devuelve la distribución de una métrica única en ~40 grupos con recuentos por rango. Esta es la herramienta que usas cuando el p75 se ve bien pero sospechas de una larga cola, o cuando quieres ver la forma completa de tus datos de rendimiento.

Parámetros

Nota: a diferencia de get_metrics, esto toma un solo metric (no metrics). Una métrica por petición.

Ejemplo: distribución de LCP en móvil

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

Respuesta analizada:

{
  "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 grupo tiene límites from/to, un count de cargas de página estimadas en ese rango, y un rating basado en dónde se sitúa el grupo con respecto a los umbrales de Core Web Vitals. El último grupo tiene to: null porque es la cola abierta.

Los anchos de los grupos son fijos por métrica: LCP usa 250ms, INP usa 25ms, CLS usa 0.025, FCP usa 200ms, TTFB usa 125ms.

Esto es útil para entender la forma de tus datos. Un p75 de 2400ms podría significar que la mayoría de los usuarios están alrededor de 2400ms, o podría significar que el 60% está por debajo de 1000ms y un segmento de tráfico móvil lento está arrastrando la cola. El histograma te dice cuál es el caso.

Dimensiones

Usa estas claves en filters o como el valor de group. Filtrar limita los datos a un segmento específico. Agrupar divide los resultados para que puedas comparar segmentos lado a lado.

General

Dispositivo y red

Atribución de métricas

Estas dimensiones te indican qué causó el valor de una métrica. Agrupa por lcpel para ver qué elementos se convierten en el LCP en tus páginas. Agrupa por inpel para encontrar las interacciones que producen el peor INP.

Ejemplos de filtros

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

Referencia de métricas

El percentil por defecto es p75. Esto es lo que Google utiliza para la clasificación de Core Web Vitals. Si el 75% de las cargas de tu página están por debajo del umbral, apruebas.

Uso de la API como un servidor MCP

El endpoint de la API es un servidor MCP totalmente compatible. Si tu herramienta de IA soporta MCP (Claude Code, Cursor, Windsurf, y otras), puedes conectarla directamente. La IA entonces tiene acceso a get_metrics, get_timeseries, y get_histogram como herramientas y puede consultar tus datos de campo como parte de cualquier conversación.

Así es como funciona CWV Superpowers: se conecta a CoreDash a través de MCP, extrae tus datos de usuarios reales, abre tu sitio en Chrome, y rastrea la causa exacta de una métrica lenta. La API proporciona la parte de "qué está sucediendo en producción", Chrome proporciona la parte de "por qué está sucediendo".

También puedes conectar el servidor MCP a tu propia configuración de IA. Apunta tu cliente MCP a https://app.coredash.app/api/mcp con tu clave de API, y tu IA puede responder preguntas como "¿qué páginas tienen el peor INP en móvil?" usando datos de campo reales en lugar de adivinar.

Límites de velocidad

Los límites son por proyecto por día y se reinician a la medianoche UTC.

150 peticiones en el plan de prueba son suficientes para la exploración manual y la depuración asistida por IA. Si estás ejecutando monitoreo automatizado en CI, los planes de pago te dan 500 por día.

Manejo de errores

Los errores se devuelven como objetos de error JSON-RPC:

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

Si obtienes -32001, comprueba que tu clave empieza por cdk_ y que no la has revocado. Si obtienes -32002, has alcanzado el límite diario. Espera al reinicio de la medianoche UTC o actualiza tu plan.