API de CoreDash: Consulta datos de Core Web Vitals de usuarios reales

Tus datos de rendimiento, en cualquier lugar que los necesites

CoreDash recopila Core Web Vitals de los 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, entrada de JSON, salida de JSON.

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 herramientas de IA como Claude, Cursor y Windsurf pueden consultar los datos de tus usuarios reales de forma directa. Pregúntale a tu IA "¿por qué mi LCP es lento en dispositivos móviles?" y esta extraerá los datos de campo reales para responderte.

Desarrollamos CWV Superpowers sobre esta base. Es un agente de IA que combina los datos de campo de CoreDash con las 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.

Autenticación

Cada solicitud 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, y después a Connect Your AI
3. Haz clic en Create API Key y cópiala. Solo se mostrará 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 la solicitud

La API utiliza JSON-RPC 2.0. Cada solicitud es un POST a:

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

El cuerpo de la solicitud tiene este aspecto:

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

El campo id puede ser cualquier número o cadena de texto. Este se devuelve en la respuesta. Existen tres herramientas: get_metrics, get_timeseries y get_histogram.

get_metrics: rendimiento actual

Devuelve los valores actuales de Core Web Vitals con las calificaciones good/improve/poor. Esta es la herramienta que utilizas 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 en bruto es un contenedor 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. Una vez parseada, tiene este aspecto:

{
  "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 entran en cada calificación. Esto suele ser más útil que el valor p75 por sí solo. Un LCP de 2450ms con un 61% de "good" significa que la mayoría de los usuarios tienen una buena experiencia, pero la cola inferior está arrastrando el p75 hacia abajo.

Ejemplo: comparar LCP en dispositivos móviles frente a escritorio

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

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

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

Dispositivos móviles a 3200ms, escritorio a 1800ms. El agregado mostraría 2500ms y pensarías "no es excelente, pero tampoco terrible". La vista agrupada muestra la verdadera historia: en escritorio está bien, pero en móviles necesita trabajo.

Ejemplo: filtrar por una página específica en móviles

Combina filters para reducir los resultados exactamente al tráfico que te interesa:

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 saber "¿ha empeorado mi LCP?" o "¿esa implementación arregló 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 parseada:

{
  "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 de un 5%) o regressing (más de un 5% peor). Esto es lo que hace que el endpoint de series temporales sea útil para la monitorización automatizada: no necesitas parsear 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 única métrica en ~40 intervalos con recuentos por rango. Esta es la herramienta que usas cuando el p75 se ve bien pero sospechas que hay una cola muy larga, o cuando quieres ver la forma completa de tus datos de rendimiento.

Parámetros

Nota: a diferencia de get_metrics, esta herramienta acepta una única metric (no metrics). Una métrica por solicitud.

Ejemplo: distribución de LCP en dispositivos móviles

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

{
  "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 intervalo tiene límites from/to, un count de cargas de página estimadas en ese rango y una calificación (rating) según dónde se sitúe el intervalo en relación con los umbrales de Core Web Vitals. El último intervalo tiene to: null porque representa una cola sin límite superior.

Las amplitudes de los intervalos son fijas por métrica: LCP utiliza 250ms, INP utiliza 25ms, CLS utiliza 0.025, FCP utiliza 200ms, TTFB utiliza 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 rondan los 2400ms, o podría significar que el 60% está por debajo de los 1000ms y un bloque de tráfico lento de móviles está tirando de la cola. El histograma te indicará cuál de las dos situaciones ocurre.

Dimensiones

Utiliza estas claves en filters o como valor en group. Filtrar reduce 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 a través de 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 predeterminado 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 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. De este modo, la IA tendrá acceso a get_metrics, get_timeseries y get_histogram como herramientas y podrá 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 los datos de tus 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" y 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 podrá responder a preguntas como "¿qué páginas tienen el peor INP en móviles?" utilizando datos de campo reales en lugar de adivinar.

Límites de peticiones

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

150 solicitudes en el plan de prueba son suficientes para la exploración manual y la depuración asistida por IA. Si estás ejecutando una monitorización automatizada en CI, los planes de pago te ofrecen 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 el error -32001, comprueba que tu clave comienza con cdk_ y que no la has revocado. Si obtienes -32002, has alcanzado el límite diario. Espera al reinicio a la medianoche UTC o actualiza tu plan.