Node Pools API

The Node Pools API lets a Connect account see how its node pools scale and change their size, autoscaler and power schedule. See Node pools and autoscaler for how the autoscaler decides.

Make sure to read the Get Started document to understand how the API works.

Note: These endpoints accept user tokens and OAuth tokens with the scopes listed per operation. Environment tokens are not accepted.

Access

You see the pools whose region is a private region enabled on one of your Connect accounts. Every account member can read them; changes need an account admin. A request for a pool you cannot see answers 403.

List node pools

GET /api/public/v1/node-pools — scope quave:read.

Parameter	Type	Required	Description
region	String	No	Only this region. Omit to list every region where you have pools.

Response:

{
  "nodePools": [
    {
      "region": "acme-prod",
      "name": "acme-prod-workers",
      "nodeRegion": "acme-prod",
      "provider": "aws",
      "role": "worker",
      "instanceType": "m6i.xlarge",
      "stateful": false,
      "powerState": "Running",
      "access": { "scope": "operator", "capabilities": { "view": true, "editScaling": true, "editPower": true, "nodePower": false, "editDisks": false } },
      "autoscaler": {
        "autoscale": true,
        "min": 2,
        "max": 6,
        "currentNodes": 3,
        "desiredNodes": 3,
        "lastDecision": { "action": "noop", "reason": "…", "at": "2026-10-15T12:19:30.000Z" },
        "utilization": null,
        "scaleUpTargets": { "cpuPercent": 70, "memoryPercent": 75 },
        "scaleDownThresholds": { "cpuPercent": 35, "memoryPercent": 37 },
        "scaleDownWindow": { "seconds": 600, "belowSince": null, "elapsedSeconds": null, "remainingSeconds": null },
        "atMin": false,
        "pendingProvisionRequests": 0
      }
    }
  ]
}

scaleDownThresholds are half of each target, rounded down. The list does not measure utilization (null); get one pool for it. When a region cannot be reached, it is listed in unavailableRegions.

Get a node pool

GET /api/public/v1/node-pool — scope quave:read.

Parameter	Type	Required	Description
region	String	Yes	Region of the pool (from the list).
name	String	Yes	Pool name.

Returns the list fields plus:

Field	Description
autoscaler.utilization	Pool CPU and memory average measured when you call this endpoint, with the same calculation the autoscaler uses (available: false when node metrics are missing; absent on stateful pools).
spec	Provider, region, role, node type (nodeTemplate.instanceType, bootVolumeSizeGb), scaling, power and, for stateful pools, volumeBinding.
nodes	One item per node: slot, nodeName, phase, autoscaleManaged, appPodCount, resources (capacity, allocatable and allocated, as on the Nodes page) and, on stateful pools, volume and powerOverride.
events	The 20 most recent pool events (type, action, severity, node, eventTime).

Update scaling

PATCH /api/public/v1/node-pool/scaling — scope quave:write:config.

Send region, name and only the fields to change: min, max, autoscale, scaleDownAction (Terminate or Stop), cpuUtilizationTargetPercent, memoryUtilizationTargetPercent (1–100), pendingPodsGracePeriodSeconds and scaleDownStabilizationSeconds (0–86400). The other settings keep their value. min cannot be above max.

{ "region": "acme-prod", "name": "acme-prod-workers", "min": 1 }

Update power

PATCH /api/public/v1/node-pool/power — scope quave:write:config.

Field	Description
mode	normal (autoscaling), schedule or override.
timezone, stop, start	For schedule: IANA timezone and two cron expressions.
override	For override: Running or Suspended.

A suspended pool stops its VMs and the workloads on them.

Update data disk autogrow (stateful pools)

PATCH /api/public/v1/node-pool/disk-autogrow — scope quave:write:config.

Send region, name, enabled and optionally triggerUsedRatio (0.5–0.95), minFreeGb, stepPercent (AWS needs at least 25), maxSizeGb (required when enabled) and cooldownMinutes.

Stop or start a node (stateful pools)

POST /api/public/v1/node-pool/node-power — scope quave:write:dangerous.

Send region, name, slot (from nodes[].slot) and power (Suspended or Running). A stopped node keeps its data disk; its workloads stay down until it starts.

Grow a data disk (stateful pools)

POST /api/public/v1/node-pool/disk-grow — scope quave:write:dangerous.

Send region, volumeName (from nodes[].volume.name) and at least one of:

• sizeGb: the new size, above the current size. Disks never shrink, and AWS allows a limited number of changes per disk in 24 hours.
• vpusPerGB (OCI disks only): the disk performance level in volume performance units per GB: 0 (lower cost), 10 (balanced, the OCI default), 20 (higher performance, the Quave standard) or 30 to 120 in steps of 10 (ultra high). OCI applies it online, after the grow when both are sent. OCI bills the level on the provider account that owns the disk.

A request with neither field answers 400.