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:
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:
| Campo | Scope |
|---|---|
vps, vpsList, availabilityGroup | vps:read |
baremetal | baremetal:read |
transit | network:read |
loadBalancer | loadbalancer:read |
natGateway | nat_gateway:read |
kubernetesCluster, kubernetesClusters | kubernetes:read |
bandwidthResources, bandwidthAggregate | el scope de cada producto que incluya |
ConsejoCrea un token dedicado solo con los scopes de lectura de arriba y fíjalo a la IP de la máquina que consulta. Si se filtra una copia, solo sirve para leer gráficas.
Tu primera consulta
Una sola petición puede pedir varios recursos a la vez, cada uno con exactamente los campos que necesitas:
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:
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
| Campo | Qué 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 / bandwidthAggregate | bandwidthResources 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
{
"data": {
"vps": {
"name": "web-1",
"metrics": {
"step": 30,
"series": [
{ "name": "cpu_usage", "unit": "RATIO", "points": [{ "ts": 1759406400, "value": 0.42 }] }
]
}
}
}
}
tses un timestamp Unix en segundos, en UTC.unitte dice cómo formatear el valor:RATIOva de 0 a 1 (0.42es un 42%),BYTES,BYTES_PER_SECOND,PACKETS_PER_SECOND,CONNECTIONS,CELSIUS,RPM,MILLISECONDS, etc.- Todas las series de un mismo resultado
metricscomparten 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
monthobtienes 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
monthanterior 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.
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.code | Significado |
|---|---|
UNAUTHENTICATED | Falta el token o no es válido |
FORBIDDEN | El token no tiene el scope de ese producto, o el servidor está suspendido |
NOT_FOUND | Ese recurso no existe en tu organización |
BAD_USER_INPUT | Argumento no válido, como un month mal formado o un campo que no existe |
METRICS_UNAVAILABLE | Las métricas no están disponibles temporalmente. El recurso se resuelve igual y las series vuelven vacías |
QUERY_TOO_COMPLEX | La petición pide demasiado de una vez (ver los límites más abajo) |
NotaLos recursos de otras organizaciones responden
NOT_FOUND, exactamente igual que un ID que no existe.
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
429conRetry-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,kubernetesClustersy cada producto debandwidthResourcesdevuelven 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.
Consejo¿Consultas la API periódicamente para un dashboard? Pide todos los recursos en una sola petición con las
metricsque pintas y reutiliza el mismorangeen todos. Cuenta como una petición contra tu límite en lugar de una por gráfica.