> ## 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. # Get a Cluster ## OpenAPI ````yaml /openapi-public.json get /clusters/{id} 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}: get: tags: - clusters summary: Get a Cluster operationId: clusters.get 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 responses: '200': description: The Cluster content: application/json: schema: $ref: '#/components/schemas/Cluster' '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: Cluster: type: object properties: id: type: string minLength: 3 maxLength: 54 html_url: type: string allOf: - maxLength: 2048 format: uri workspace_id: type: string minLength: 2 maxLength: 53 name: type: string minLength: 1 maxLength: 63 pattern: ^[a-z0-9](?:[-a-z0-9]*[a-z0-9])?$ description: A DNS label, unique in the Workspace. examples: - shop kind: type: string enum: - hosted - attached region_id: anyOf: - type: string minLength: 3 maxLength: 54 - type: 'null' description: The Region of a hosted Cluster; null for an attached one. state: type: string enum: - provisioning - awaiting_node - awaiting_agent - configuring - ready - degraded - disconnected - failed - deleting - deleted description: >- `provisioning`: the hosted control plane starts. `awaiting_node`: join a server with a join token. `awaiting_agent`: install the agent (attached) or wait for it. `configuring`: the baseline is placed. `disconnected`: the agent stopped calling; workloads keep running. capabilities: type: array items: type: string enum: - https_ingress - persistent_volumes - resource_metrics storage_classes: type: array items: $ref: '#/components/schemas/ClusterStorageClass' description: >- The StorageClasses Akua runs here and an Install can use, from its healthy storage capabilities. OUTPUT_ONLY. No class is the cluster default: an Install names one on every volume, the one asked for or the one Akua picks. ready_nodes: type: integer minimum: 0 conditions: type: array items: $ref: '#/components/schemas/Condition' maxItems: 32 description: >- What needs attention now; empty when nothing does. Reasons: - `agent-offline` (warning): the agent is not connected; workloads keep running and nothing new rolls out until it reconnects. - `updater-behind` (warning): the updater has run another release than the agent for 30 minutes, so no agent release is offered. Remedy `run-agent-install` on an attached Cluster; none on a hosted one, whose agent and updater Akua re-applies. - `needs-customer-upgrade` (warning): the offered agent release changes objects outside the access you granted, so it was not applied. Remedy `customer-upgrade` names the missing permissions and the `helm upgrade` command. - `bundle-too-large` (warning): the offered agent release is too large to deliver or to keep as a rollback copy, so it was not applied. - `update-rolled-back`, `baseline-degraded` (warning): a capability release failed its health gate and was rolled back, or a capability is not healthy; see the Cluster’s capabilities. A list shows `baseline-degraded` from the Cluster state only; `update-rolled-back` appears when the Cluster is read on its own. - When `state` is `failed`, one error whose reason says why: `control-plane-unready`, `enrollment-expired`, `agent-unsupported`, `baseline-failed`, `baseline-rollback-failed`, `cleanup-unconfirmed`, `node-removal-failed` or `agent-bundle-failed`. operation_id: type: string minLength: 2 maxLength: 192 connector: $ref: '#/components/schemas/ClusterConnector' created_at: type: integer minimum: 0 description: Unix timestamp (seconds) etag: type: string required: - id - html_url - workspace_id - name - kind - region_id - state - capabilities - ready_nodes - conditions - operation_id - connector - created_at - etag 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 ClusterStorageClass: type: object properties: name: type: string minLength: 1 maxLength: 253 pattern: >- ^[a-z0-9](?:[-a-z0-9]*[a-z0-9])?(?:\.[a-z0-9](?:[-a-z0-9]*[a-z0-9])?)*$ description: A Kubernetes StorageClass name. examples: - local-path attachment: type: string enum: - node_local - network description: >- `node_local`: the volume lives on the disk of the node its first Pod ran on, fastest and fixed to that node. `network`: the volume attaches over the network and follows its Pod to another node. required: - name - attachment 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 ClusterConnector: type: object properties: status: type: string enum: - pending - connected - offline - revoked description: '`pending`: installed or enrolled, no contact yet.' version: type: string description: The release it runs. last_seen_at: type: integer minimum: 0 description: Unix timestamp (seconds) required: - status 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 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.