Skip to main content

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.

ParameterTypeRequiredDescription
regionStringNoOnly 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",
"readOnly": false,
"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.

readOnly: true marks a pool managed by infra (GitOps). Its scaling and power cannot be changed here: those requests answer 409 with "error": "Managed by infra (GitOps)", a details sentence and data.code managed_by_gitops. To change such a pool, contact support. Stopping or starting one node, growing a data disk and the disk autogrow policy stay available.

Get a node pool​

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

ParameterTypeRequiredDescription
regionStringYesRegion of the pool (from the list).
nameStringYesPool name.

Returns the list fields plus:

FieldDescription
autoscaler.utilizationPool 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).
specProvider, region, role, node type (nodeTemplate.instanceType, bootVolumeSizeGb), scaling, power and, for stateful pools, volumeBinding.
nodesOne 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.
eventsThe 20 most recent pool events (type, action, severity, node, eventTime).
resizeOperationsStateful pools: the 5 most recent node resizes (name, slot, fromShape, toShape, phase, failureReason, rollbackReason, startedAt, completedAt). A resize is finished when phase is Completed, RolledBack or Failed.

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.

FieldDescription
modenormal (autoscaling), schedule or override.
timezone, stop, startFor schedule: IANA timezone and two cron expressions.
overrideFor 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.

Resize a data node (stateful pools)​

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

Changes the CPU and memory of one node of a stateful pool (flexible shapes, OCI). The VM stops, changes size and starts again: everything on the node, including a single-instance database, is down for about 3 to 8 minutes. The data disk stays attached.

FieldDescription
region, nameThe pool.
slotThe node (nodes[].slot).
ocpusNew number of OCPUs (whole number).
memoryGbNew memory in GB (whole number, at least 8, 1 to 64 GB per OCPU).
dryRuntrue returns the plan without changing anything.
confirmThe node name (nodes[].nodeName, or the slot when it has none). Required unless dryRun.

Send dryRun: true first. The response plan has current (size now), target, currentAllocatable, requested (what the pods on the node request today), estimatedAllocatable (CPU cores and memory bytes after the resize, an estimate) and downtime. Then send the same size with confirm to start it; the response has the operation and the plan. Follow it in resizeOperations of Get a node pool.

{
"region": "acme-prod",
"name": "acme-prod-data",
"slot": "acme-prod-data-0",
"ocpus": 2,
"memoryGb": 16,
"confirm": "acme-prod-data-6009"
}

Refusals:

  • 400: the size is outside the limits, equals the current size, or its estimated allocatable is below what the pods on the node request (the message says the smallest size that fits), or the confirmation does not match.
  • 409: another resize runs in the pool (one at a time), the node is stopped or being terminated, the node was adopted, the provider has fixed instance types (AWS: contact support), or the node's current size is not reported yet.