Todas las métricas que ves en my.cubepath.com salen de la API GraphQL de CubePath. Es el mismo endpoint que usa el panel, y puedes consultarlo tú mismo para montar tus propios dashboards, informes y comprobaciones de salud.

 
POST https://api.cubepath.com/graphql

Es de solo lectura y cubre métricas y tráfico: VPS, grupos de disponibilidad, baremetal (tráfico, ancho de banda y sensores BMC), tránsito IP, balanceadores de carga, NAT gateways y clústeres de Kubernetes. Para crear o modificar recursos, usa la API REST o el servidor MCP.

Autenticación

Usa un token de API en cualquiera de las dos cabeceras:

bash
curl https://api.cubepath.com/graphql \
  -H "Content-Type: application/json" \
  -H "Authorization: Bearer TU_TOKEN_DE_API" \
  -d '{"query":"{ vpsList { id name } }"}'

X-API-Key: TU_TOKEN_DE_API también funciona. Una petición con token no necesita la cabecera X-Requested-With, aunque sea un POST.

Cada campo comprueba el scope de lectura de su producto, así que a un token de monitorización le bastan los scopes de lectura:

CampoScope
vps, vpsList, availabilityGroupvps:read
baremetalbaremetal:read
transitnetwork:read
loadBalancerloadbalancer:read
natGatewaynat_gateway:read
kubernetesCluster, kubernetesClusterskubernetes:read
bandwidthResources, bandwidthAggregateel scope de cada producto que incluya

Tu primera consulta

Una sola petición puede pedir varios recursos a la vez, cada uno con exactamente los campos que necesitas:

graphql
query Resumen($id: ID!) {
  vps(id: $id) {
    name
    metrics(range: H6, metrics: [CPU_USAGE, MEMORY_USAGE]) {
      step
      series { name unit points { ts value } }
    }
    bandwidthUsage { inBytes outBytes totalBytes }
  }
  kubernetesClusters {
    name
    health { up nodesReady nodesTotal podsPending }
  }
}

Envíala como JSON con query y variables. Por ejemplo, una versión más corta de la consulta anterior que pide solo la CPU:

bash
curl https://api.cubepath.com/graphql \
  -H "Content-Type: application/json" \
  -H "Authorization: Bearer TU_TOKEN_DE_API" \
  -d '{"query":"query($id: ID!){ vps(id:$id){ name metrics(range: H6, metrics:[CPU_USAGE]){ step series{ name unit points{ ts value } } } } }","variables":{"id":"1234"}}'

Qué puedes consultar

CampoQué devuelve
vps(id) / vpsList(projectId)Series de CPU, memoria, E/S de disco y red, más el ancho de banda del mes. vpsList devuelve hasta 200 servidores
availabilityGroup(uuid)CPU media y memoria total del grupo, y cuántos servidores tiene
baremetal(id)Tráfico y paquetes por segundo, el ancho de banda del ciclo de facturación en curso y la transferencia que incluye, el tráfico de los últimos 30 días y los sensores BMC (temperaturas, ventiladores, estado de energía)
transit(id)Tráfico y paquetes por segundo de tu puerto de tránsito IP
loadBalancer(uuid)Conexiones activas, conexiones nuevas por segundo, tráfico de entrada y salida, y el ancho de banda del mes
natGateway(uuid)Tráfico de entrada y salida, y el ancho de banda del mes
kubernetesCluster(uuid) / kubernetesClusters(projectId)Salud del servidor de API, cada nodo con sus condiciones y recursos, y las series del clúster (nodos listos, pods pendientes y fallidos, latencia de la API)
bandwidthResources / bandwidthAggregatebandwidthResources lista todos los servicios que mueven tráfico público, con su ancho de banda y la transferencia que incluyen; bandwidthAggregate suma su tráfico por ubicación, producto, proyecto o servicio. Entre los dos alimentan la página Uso de ancho de banda

Rangos de tiempo

metrics(range:) acepta los mismos rangos que el panel: H1, H3, H6, H12, H24, D3, D7 y D30. Por defecto, H1.

Los rangos largos vuelven con un step mayor (el tamaño de cada intervalo, en segundos), así que una gráfica de 30 días tiene unos 300 puntos y no decenas de miles.

Cómo leer un resultado

json
{
  "data": {
    "vps": {
      "name": "web-1",
      "metrics": {
        "step": 30,
        "series": [
          { "name": "cpu_usage", "unit": "RATIO", "points": [{ "ts": 1759406400, "value": 0.42 }] }
        ]
      }
    }
  }
}
  • ts es un timestamp Unix en segundos, en UTC.
  • unit te dice cómo formatear el valor: RATIO va de 0 a 1 (0.42 es un 42%), BYTES, BYTES_PER_SECOND, PACKETS_PER_SECOND, CONNECTIONS, CELSIUS, RPM, MILLISECONDS, etc.
  • Todas las series de un mismo resultado metrics comparten los mismos timestamps, así que puedes pintarlas en una sola gráfica sin alinearlas tú.

Totales de ancho de banda

bandwidthUsage devuelve el tráfico de un servicio hasta ahora (inBytes, outBytes y totalBytes) y el periodo que cubre, de periodStart a periodEnd (timestamps Unix, en UTC).

En los VPS, balanceadores de carga y NAT gateways el periodo es el mes natural (UTC). bandwidthUsage(month: "2026-09") devuelve ese mes, y si omites month obtienes el mes en curso hasta ahora. El formato es estrictamente YYYY-MM.

En los servidores dedicados el periodo es el ciclo de facturación del servidor. Empieza a las 00:00 UTC del día del mes en que se emite su factura recurrente, o el día 1 si el servidor no tiene factura recurrente, y periodStart te dice qué día es. La cuenta nunca empieza antes de que el servidor se asignara a tu organización.

  • Sin month obtienes el ciclo en curso hasta ahora. Mientras dura, un ciclo que empezó el mes anterior incluye también esos días, así que también aparecen en las cifras de ese mes.
  • Con un month anterior obtienes el ciclo que estaba en marcha al terminar ese mes, desde su inicio hasta el final del mes.
  • Los totales se actualizan más o menos cada 30 minutos. Justo después de la renovación, el ciclo anterior puede seguir apareciendo hasta 30 minutos.
  • Las cifras de los meses anteriores a noviembre de 2026 mantienen las fechas del mes natural.

includedBytes es la transferencia de salida incluida en cada ciclo de facturación de un servidor dedicado, en bytes (1 TB cuenta como 1024^4 bytes): la del add-on de ancho de banda que tenga el servidor o, si no tiene ninguno, la de su plan. Solo cuenta el tráfico de salida (outBytes). Si en ese momento no se puede leer, vuelve como null, y las cifras de tráfico se devuelven igualmente. bandwidthResources da el mismo includedBytes para los servidores dedicados, y la transferencia mensual del plan para los VPS.

graphql
query Dedicado($id: ID!) {
  baremetal(id: $id) {
    label
    includedBytes
    bandwidthUsage { outBytes periodStart periodEnd }
  }
}

outBytes dividido entre includedBytes es la parte de la transferencia incluida que llevas gastada en el ciclo.

En todos los campos de ancho de banda, inBytes es siempre el tráfico que entra en tu servicio y outBytes el que sale, sea cual sea el producto. En cambio, las series de tráfico de baremetal y transit (network_in_bytes, network_out_bytes y sus paquetes) se miden en el puerto del switch, así que en esas series network_in_bytes es el tráfico que envía tu servidor.

Errores

Una petición que GraphQL acepta siempre responde HTTP 200. Cuando falla un campo, ese campo vale null y errors explica el motivo, mientras el resto de la petición se resuelve igualmente:

extensions.codeSignificado
UNAUTHENTICATEDFalta el token o no es válido
FORBIDDENEl token no tiene el scope de ese producto, o el servidor está suspendido
NOT_FOUNDEse recurso no existe en tu organización
BAD_USER_INPUTArgumento no válido, como un month mal formado o un campo que no existe
METRICS_UNAVAILABLELas métricas no están disponibles temporalmente. El recurso se resuelve igual y las series vuelven vacías
QUERY_TOO_COMPLEXLa petición pide demasiado de una vez (ver los límites más abajo)

Límites

  • 600 peticiones por minuto por token. Cada petición cuenta una vez, pida lo que pida. Por encima del límite recibes un 429 con Retry-After.
  • Una sola petición puede devolver hasta unos 24.000 puntos: por ejemplo 200 series de una hora, u 80 series de 30 días. Si necesitas más, divídela en dos.
  • Consultas de hasta 6 niveles de profundidad, 15 alias y 2.000 tokens (las palabras y símbolos del texto de la consulta, no tokens de API). No se aceptan varias operaciones enviadas en un mismo array JSON (batching).
  • vpsList, kubernetesClusters y cada producto de bandwidthResources devuelven hasta 200 elementos.

Esquema y herramientas

El esquema está abierto a llamadas autenticadas mediante introspección estándar, así que herramientas como GraphQL Code Generator, Postman o Insomnia pueden cargarlo con tu token. La introspección anónima se rechaza.