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

Tus datos de rendimiento, dondequiera 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, entrada JSON, salida JSON.

El caso de uso más interesante: conectar tu IA. La API de CoreDash usa 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 usuarios reales directamente. Pregúntale a tu IA "¿por qué mi LCP es lento en dispositivos móviles?" 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 esto 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 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, 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 varias claves y revocarlas desde la misma página.

Formato de 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 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 de bueno/mejorar/pobre. 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 en bruto 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. Al analizarla, 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 entran en cada calificación. A menudo, esto es más útil que el valor p75 por sí solo. Un LCP de 2450 ms 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 el 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 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 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 3200 ms, escritorio a 1800 ms. El agregado mostraría 2500 ms y pensarías "no es genial, pero no es terrible". La vista agrupada muestra la historia real: el escritorio está bien, los dispositivos móviles necesitan trabajo.

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

Combina filters para reducir exactamente el 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 "¿ha empeorado mi LCP?" y "¿ese despliegue solucionó la regresión?".

Parámetros

Ejemplo: tendencia del 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 objeto 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 timeseries sea útil para la supervisión automatizada: no necesitas analizar los puntos de datos tú mismo para saber si las cosas están empeorando.

get_histogram: forma de distribución

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

Parámetros

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

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

La amplitud de los rangos es fija por métrica: LCP usa 250 ms, INP usa 25 ms, CLS usa 0.025, FCP usa 200 ms, TTFB usa 125 ms.

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

Dimensiones

Usa estas claves en filters o como valor de 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 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 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 admite MCP (Claude Code, Cursor, Windsurf y otros), puedes conectarla directamente. 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 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 podrá responder preguntas como "¿qué páginas tienen el peor INP en dispositivos móviles?" usando 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 peticiones en el plan de prueba son suficientes para la exploración manual y la depuración asistida por IA. Si estás ejecutando un monitoreo automatizado en CI, los planes de pago te brindan 500 por día.

Manejo de errores

Los errores regresan 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 comience con cdk_ y que no la hayas revocado. Si obtienes -32002, has alcanzado el límite diario. Espera al restablecimiento de la medianoche UTC o actualiza tu plan.