---
title: "API GraphQL"
description: "Consulta métricas, ancho de banda y salud de Kubernetes desde tus propias herramientas con la API GraphQL de CubePath: autenticación, campos, errores y límites."
category: "Ajustes"
language: es
source: https://cubepath.com/es/docs/products/ajustes/api-graphql
updated: 2026-10-02
---

# API GraphQL

Todas las métricas que ves en [my.cubepath.com](https://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](/docs/products/ajustes/tokens-api) o el [servidor MCP](/docs/products/ajustes/mcp-server-es).

## Autenticación

Usa un [token de API](/docs/products/ajustes/tokens-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:

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

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

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

```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

| 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 mes, 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 API server, cada nodo con sus condiciones y recursos, y las series del cluster (nodos listos, pods pendientes y fallidos, latencia de la API) |
| `bandwidthResources` / `bandwidthAggregate` | Todos los servicios que mueven tráfico público y su tráfico sumado por ubicación, producto, proyecto o servicio. Es lo que alimenta la página 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ú.

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

| `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) |

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