> ## Documentation Index > Fetch the complete documentation index at: https://docs.akua.dev/llms.txt > Use this file to discover all available pages before exploring further. # List nodes ## OpenAPI ````yaml /openapi-public.json get /clusters/{id}/nodes openapi: 3.1.0 info: title: Akua API version: 1.0.0 description: >- Manage installs and their asynchronous operations. Authenticate with a session bearer token and select a Workspace using Akua-Context. contact: name: Akua API support email: support@akua.dev url: https://docs.akua.dev/ servers: - url: https://api.akua.dev/v1 security: [] tags: - name: operations - name: installs - name: Organizations - name: Billing accounts - name: workspaces - name: regions - name: Dashboard Overview - name: products - name: offers - name: Order Drafts - name: packages - name: Auth - name: API Tokens - name: Quota adjustments - name: Workspace services - name: Vault connections - name: clusters - name: Node pools - name: Nodes - name: machines - name: Sandboxes - name: OpenCode Servers - name: vaults - name: vaultSecrets paths: /clusters/{id}/nodes: get: tags: - Nodes summary: List nodes operationId: nodes.list parameters: - name: id in: path schema: type: string minLength: 3 maxLength: 54 required: true - name: akua-context in: header schema: type: string minLength: 1 maxLength: 53 description: >- Optional workspace/scope context for the request. Carries a single workspace wire id (`ws_…`) today. Only needed for broad tokens - a workspace-owned token implies its workspace. examples: - ws_j572abc123def4 required: false - name: cursor in: query schema: type: string maxLength: 512 required: false - name: limit in: query schema: type: integer minimum: 1 maximum: 100 required: false - name: node_pool_id in: query schema: $ref: '#/components/schemas/NodePoolId' required: false responses: '200': description: Nodes, by name content: application/json: schema: $ref: '#/components/schemas/NodeList' '400': description: The request is malformed. content: application/json: schema: $ref: '#/components/schemas/ApiBadRequest' '401': description: Missing, invalid or expired credential. content: application/json: schema: $ref: '#/components/schemas/ApiUnauthorized' '403': description: The credential may not act in this workspace. content: application/json: schema: $ref: '#/components/schemas/ApiForbidden' '404': description: The resource was not found in this workspace. content: application/json: schema: $ref: '#/components/schemas/ApiNotFound' '409': description: >- The request conflicts with existing resource state or immutable intent. | The resource changed since the etag the client sent; the current etag is in the metadata. | The idempotency key was already used for a different request. content: application/json: schema: anyOf: - $ref: '#/components/schemas/ApiConflict' - $ref: '#/components/schemas/ApiPreconditionFailed' - $ref: '#/components/schemas/ApiIdempotencyConflict' '410': description: The resource is permanently unavailable. content: application/json: schema: $ref: '#/components/schemas/ApiGone' '422': description: The request is well-formed but cannot be processed. content: application/json: schema: $ref: '#/components/schemas/ApiUnprocessable' '429': description: The caller is over its per-minute budget. content: application/json: schema: $ref: '#/components/schemas/ApiTooManyRequests' '500': description: The server failed to handle the request. content: application/json: schema: $ref: '#/components/schemas/ApiInternalServerError' '502': description: An upstream provider failed. content: application/json: schema: $ref: '#/components/schemas/ApiExternalServiceError' '503': description: The service is temporarily unavailable. content: application/json: schema: $ref: '#/components/schemas/ApiServiceUnavailable' '504': description: An upstream provider did not answer in time. content: application/json: schema: $ref: '#/components/schemas/ApiGatewayTimeout' security: - BearerAuth: [] components: schemas: NodePoolId: type: string pattern: ^[a-z](?:[-a-z0-9]{0,38}[a-z0-9])?$ description: >- A DNS label of at most 40 characters, unique in the Cluster. Every node of the pool carries it as the label `akua.dev/node-pool`. examples: - default NodeList: type: object properties: data: type: array items: $ref: '#/components/schemas/Node' maxItems: 500 has_more: type: boolean next_cursor: anyOf: - type: string maxLength: 512 - type: 'null' required: - data - has_more - next_cursor additionalProperties: false ApiBadRequest: type: object properties: _tag: type: string enum: - Validation success: type: boolean enum: - false errors: type: array prefixItems: - $ref: '#/components/schemas/ApiErrorEntry' minItems: 1 items: $ref: '#/components/schemas/ApiErrorEntry' result: type: object additionalProperties: false required: - _tag - success - errors - result additionalProperties: false ApiUnauthorized: type: object properties: _tag: type: string enum: - Unauthorized success: type: boolean enum: - false errors: type: array prefixItems: - $ref: '#/components/schemas/ApiErrorEntry' minItems: 1 items: $ref: '#/components/schemas/ApiErrorEntry' result: type: object additionalProperties: false required: - _tag - success - errors - result additionalProperties: false ApiForbidden: type: object properties: _tag: type: string enum: - Forbidden success: type: boolean enum: - false errors: type: array prefixItems: - $ref: '#/components/schemas/ApiErrorEntry' minItems: 1 items: $ref: '#/components/schemas/ApiErrorEntry' result: type: object additionalProperties: false required: - _tag - success - errors - result additionalProperties: false ApiNotFound: type: object properties: _tag: type: string enum: - NotFound success: type: boolean enum: - false errors: type: array prefixItems: - $ref: '#/components/schemas/ApiErrorEntry' minItems: 1 items: $ref: '#/components/schemas/ApiErrorEntry' result: type: object additionalProperties: false required: - _tag - success - errors - result additionalProperties: false ApiConflict: type: object properties: _tag: type: string enum: - Conflict success: type: boolean enum: - false errors: type: array prefixItems: - $ref: '#/components/schemas/ApiErrorEntry' minItems: 1 items: $ref: '#/components/schemas/ApiErrorEntry' result: type: object additionalProperties: false required: - _tag - success - errors - result additionalProperties: false ApiPreconditionFailed: type: object properties: _tag: type: string enum: - PreconditionFailed success: type: boolean enum: - false errors: type: array prefixItems: - type: object properties: code: type: number enum: - 7006 message: type: string metadata: type: object properties: current_etag: type: string required: - current_etag allOf: - type: object additionalProperties: type: string required: - code - message - metadata additionalProperties: false maxItems: 1 minItems: 1 result: type: object additionalProperties: false required: - _tag - success - errors - result additionalProperties: false ApiIdempotencyConflict: type: object properties: _tag: type: string enum: - IdempotencyConflict success: type: boolean enum: - false errors: type: array prefixItems: - $ref: '#/components/schemas/ApiErrorEntry' minItems: 1 items: $ref: '#/components/schemas/ApiErrorEntry' result: type: object additionalProperties: false required: - _tag - success - errors - result additionalProperties: false ApiGone: type: object properties: _tag: type: string enum: - Gone success: type: boolean enum: - false errors: type: array prefixItems: - $ref: '#/components/schemas/ApiErrorEntry' minItems: 1 items: $ref: '#/components/schemas/ApiErrorEntry' result: type: object additionalProperties: false required: - _tag - success - errors - result additionalProperties: false ApiUnprocessable: type: object properties: _tag: type: string enum: - Unprocessable success: type: boolean enum: - false errors: type: array prefixItems: - $ref: '#/components/schemas/ApiErrorEntry' minItems: 1 items: $ref: '#/components/schemas/ApiErrorEntry' result: type: object additionalProperties: false required: - _tag - success - errors - result additionalProperties: false ApiTooManyRequests: type: object properties: _tag: type: string enum: - TooManyRequests success: type: boolean enum: - false errors: type: array prefixItems: - $ref: '#/components/schemas/ApiErrorEntry' minItems: 1 items: $ref: '#/components/schemas/ApiErrorEntry' result: type: object additionalProperties: false required: - _tag - success - errors - result additionalProperties: false ApiInternalServerError: type: object properties: _tag: type: string enum: - InternalServerError success: type: boolean enum: - false errors: type: array prefixItems: - type: object properties: code: type: number enum: - 7009 message: type: string enum: - Internal server error required: - code - message additionalProperties: false maxItems: 1 minItems: 1 result: type: object additionalProperties: false required: - _tag - success - errors - result additionalProperties: false ApiExternalServiceError: type: object properties: _tag: type: string enum: - ExternalServiceError success: type: boolean enum: - false errors: type: array prefixItems: - $ref: '#/components/schemas/ApiErrorEntry' minItems: 1 items: $ref: '#/components/schemas/ApiErrorEntry' result: type: object additionalProperties: false required: - _tag - success - errors - result additionalProperties: false ApiServiceUnavailable: type: object properties: _tag: type: string enum: - ServiceUnavailable success: type: boolean enum: - false errors: type: array prefixItems: - $ref: '#/components/schemas/ApiErrorEntry' minItems: 1 items: $ref: '#/components/schemas/ApiErrorEntry' result: type: object additionalProperties: false required: - _tag - success - errors - result additionalProperties: false ApiGatewayTimeout: type: object properties: _tag: type: string enum: - GatewayTimeout success: type: boolean enum: - false errors: type: array prefixItems: - $ref: '#/components/schemas/ApiErrorEntry' minItems: 1 items: $ref: '#/components/schemas/ApiErrorEntry' result: type: object additionalProperties: false required: - _tag - success - errors - result additionalProperties: false Node: type: object properties: name: type: string minLength: 1 maxLength: 253 pattern: ^[a-z0-9](?:[-a-z0-9.]*[a-z0-9])?$ cluster_id: type: string minLength: 3 maxLength: 54 source: $ref: '#/components/schemas/NodeSource' state: type: string enum: - provisioning - restoring - ready - draining - deleted description: >- `provisioning`: its Machine is being created or its server is joining. `ready`: joined; Kubernetes readiness is `ready` and `conditions`. `draining`: cordoned and evicting Pods before it is removed. `deleted`: removed from the Cluster. conditions: type: array items: $ref: '#/components/schemas/Condition' maxItems: 32 description: >- What needs attention now; empty when nothing does. Reasons: - `not-ready` (warning): Kubernetes reports the node not ready. - `join-timeout` (error): the server started but never joined; its Machine was deleted. - `drain-timeout` (warning): Pods did not leave within the drain bound; the node was removed anyway. - `trial-ended` (warning): the node’s free trial Machine was paused. Remedy `add-billing`. - `capacity-unavailable`, `provider-refused`, `provider-unavailable` (error): its Machine could not be created; forwarded from the Machine. ready: type: boolean description: Kubernetes `Ready`; false until the node joined. provider_id: anyOf: - type: string maxLength: 256 - type: 'null' description: The node's `spec.providerID`; null without a cloud controller. labels: type: object additionalProperties: type: string kubelet_version: anyOf: - type: string maxLength: 64 - type: 'null' created_at: anyOf: - type: integer minimum: 0 maximum: 9007199254740991 description: Unix timestamp (seconds) - type: 'null' required: - name - cluster_id - source - state - conditions - ready - provider_id - labels - kubelet_version - created_at additionalProperties: false ApiErrorEntry: type: object properties: code: type: integer minimum: -9007199254740991 maximum: 9007199254740991 description: Machine-readable error code examples: - 7002 message: type: string description: Human-readable error message examples: - Resource not found path: type: array items: type: string description: Field path that caused the error, when applicable examples: - - body - name metadata: type: object additionalProperties: type: string required: - code - message additionalProperties: false NodeSource: anyOf: - type: object properties: kind: type: string enum: - node_pool node_pool_id: $ref: '#/components/schemas/NodePoolId' machine_id: type: string minLength: 3 maxLength: 54 required: - kind - node_pool_id - machine_id additionalProperties: false - type: object properties: kind: type: string enum: - joined description: >- Your own server, joined with a join token. Removing it drains it and removes it from the Cluster; the server itself is untouched. required: - kind additionalProperties: false Condition: type: object properties: reason: type: string maxLength: 64 pattern: ^[a-z0-9]+(?:-[a-z0-9]+)*$ description: Kebab-case reason; the resource documents the reasons it reports. examples: - agent-offline severity: type: string enum: - error - warning - info description: >- `error`: the resource failed; the condition says why. `warning`: it is limited or held until the person acts or it recovers. `info`: worth knowing, nothing to do. message: type: string maxLength: 512 description: Safe to show the person as is. remedy: anyOf: - $ref: '#/components/schemas/FailureRemedy' - type: 'null' description: What the person can do; null when nothing they do helps. last_transition_at: type: integer minimum: 0 description: Unix timestamp (seconds) when this condition last changed. required: - reason - severity - message - remedy - last_transition_at additionalProperties: false FailureRemedy: anyOf: - type: object properties: kind: type: string enum: - free-capacity metric: type: string enum: - kaas/clusters - compute/machines - compute/cpu - compute/memory - compute/machines_concurrency - compute/managed_vm_trial - agents/turns_concurrency - agents/sandboxes - agents/sandboxes_running - agents/retained_filesystem_lifetime - codemode/executions - api/secrets_access - api/secrets_write - domain_routing/preview_hostnames - domain_routing/custom_domains - source_control/repositories limit: type: integer usage: type: integer hint: type: string maxLength: 256 required: - kind - metric - limit - usage - hint additionalProperties: false - type: object properties: kind: type: string enum: - upgrade-plan metric: type: string enum: - kaas/clusters - compute/machines - compute/cpu - compute/memory - compute/machines_concurrency - compute/managed_vm_trial - agents/turns_concurrency - agents/sandboxes - agents/sandboxes_running - agents/retained_filesystem_lifetime - codemode/executions - api/secrets_access - api/secrets_write - domain_routing/preview_hostnames - domain_routing/custom_domains - source_control/repositories required: - kind - metric additionalProperties: false - type: object properties: kind: type: string enum: - grant-access namespace: anyOf: - type: string maxLength: 63 - type: 'null' permissions: type: array prefixItems: - type: string maxLength: 256 minItems: 1 items: type: string maxLength: 256 maxItems: 64 required: - kind - namespace - permissions additionalProperties: false - type: object properties: kind: type: string enum: - reconnect what: type: string enum: - cluster-agent - connection required: - kind - what additionalProperties: false - type: object properties: kind: type: string enum: - add-machine required: - kind additionalProperties: false - type: object properties: kind: type: string enum: - add-billing required: - kind additionalProperties: false - type: object properties: kind: type: string enum: - change-input path: type: array items: type: string maxLength: 128 maxItems: 32 required: - kind - path additionalProperties: false - type: object properties: kind: type: string enum: - retry after_seconds: anyOf: - type: integer - type: 'null' required: - kind - after_seconds additionalProperties: false - type: object properties: kind: type: string enum: - run-agent-install description: >- Run the command from `POST /v1/clusters/{id}/connector_install` again; it re-applies the ClusterConnector and its updater at one release. required: - kind additionalProperties: false - type: object properties: kind: type: string enum: - customer-upgrade description: >- The change needs rights the agent was not granted. Run `command` (a `helm upgrade`, no secret) with an identity that holds `permissions`, or grant them to the agent. permissions: type: array prefixItems: - type: string maxLength: 256 minItems: 1 items: type: string maxLength: 256 maxItems: 64 command: type: string minLength: 1 maxLength: 8192 required: - kind - permissions - command additionalProperties: false securitySchemes: BearerAuth: description: Bearer token for the authenticated caller. type: http scheme: bearer ```` This documentation is built and hosted on [Mintlify](https://mintlify.com), a developer documentation platform.