API GraphQL

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, availability groups, baremetal (tráfico, ancho de banda y sensores BMC), tránsito IP, load balancers, NAT gateways y clusters 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:

Consejo

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

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

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

• 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ú.

Ancho de banda mensual

bandwidthUsage(month: "2026-09") devuelve el tráfico de ese mes natural (UTC). Si omites month, devuelve el mes en curso hasta ahora. El formato es estrictamente YYYY-MM.

En 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.

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:

Nota

Los 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 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. No se aceptan arrays de operaciones en lote.
• 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.

Consejo

¿Consultas para un dashboard? Pide todos los recursos en una sola petición con las metrics que pintas y reutiliza el mismo range en todos. Cuenta como una petición contra tu límite en lugar de una por gráfica.