> ## Documentation Index > Fetch the complete documentation index at: https://docs.aireserve.com/llms.txt > Use this file to discover all available pages before exploring further. # List GPU clusters > Every multi-node cluster in the organization, newest first, including terminated ones. Requires compute `read` access. ## OpenAPI ````yaml /api-reference/openapi.json get /v1/gpu/clusters openapi: 3.0.3 info: title: AI Reserve Gateway API description: >- The AI Reserve API surface — OpenAI-compatible chat completions, Anthropic-compatible messages, Bedrock Converse, images, video, files, text-to-speech, realtime voice sessions, and provider-hidden GPU infrastructure — all behind one endpoint and one API key. version: 1.0.0 servers: - url: https://api.aireserve.com security: - bearerAuth: [] tags: - name: Customers description: >- Per-end-customer usage, cost, and billable amounts for organizations that tag requests with their own customers. - name: GPU Infrastructure description: >- Provision and manage provider-hidden GPU instances. The recommended Instances API accepts workload requirements and an hourly price ceiling; AI Reserve handles provider placement internally. Every mutation is asynchronous and returns an operation to poll. - name: Customer keys description: >- Mint, list, and revoke API keys pinned to your own end customers (and their organizations), so spend splits per customer without per-request tagging. paths: /v1/gpu/clusters: get: tags: - GPU Infrastructure summary: List GPU clusters description: >- Every multi-node cluster in the organization, newest first, including terminated ones. Requires compute `read` access. operationId: listGpuClusters parameters: - name: cursor in: query required: false description: Opaque cursor from a previous page. schema: type: string responses: '200': description: OK content: application/json: schema: type: object properties: data: type: array items: type: object properties: id: type: string format: uuid pattern: >- ^([0-9a-fA-F]{8}-[0-9a-fA-F]{4}-[1-8][0-9a-fA-F]{3}-[89abAB][0-9a-fA-F]{3}-[0-9a-fA-F]{12}|00000000-0000-0000-0000-000000000000|ffffffff-ffff-ffff-ffff-ffffffffffff)$ name: type: string status: type: string enum: - requested - provisioning - starting - running - degraded - terminating - terminated - reconciling - failed description: >- `degraded`: the cluster was admitted running and some nodes have since left `running`. Billing continues while you recover or terminate it. desiredState: type: string enum: - running - terminated description: >- A cluster has no stopped state; terminate releases every node. accelerator: type: object properties: model: type: string description: >- Provider-independent accelerator model, for example `H200_141GB`. count: type: integer minimum: -9007199254740991 maximum: 9007199254740991 description: Total GPUs across every node. perNode: type: integer minimum: -9007199254740991 maximum: 9007199254740991 required: - model - count - perNode additionalProperties: false topology: type: object properties: nodes: type: integer minimum: -9007199254740991 maximum: 9007199254740991 gpusPerNode: type: integer minimum: -9007199254740991 maximum: 9007199254740991 orchestrator: type: string enum: - none - slurm - ray interconnect: type: string enum: - private_network description: >- Nodes share a private high-bandwidth network. `MASTER_ADDR`, `NODE_RANK` and `NCCL_SOCKET_IFNAME` are preset on every node. required: - nodes - gpusPerNode - orchestrator - interconnect additionalProperties: false runtime: type: object properties: type: type: string enum: - container profile: nullable: true description: >- Provider-neutral maintained runtime profile. Null for a custom image. type: string required: - type - profile additionalProperties: false location: type: object properties: region: nullable: true type: string required: - region additionalProperties: false storage: type: object properties: rootGbPerNode: type: integer minimum: -9007199254740991 maximum: 9007199254740991 rootPersistence: type: string enum: - ephemeral volumeId: nullable: true description: Alias for `persistent.volumeId`. type: string format: uuid pattern: >- ^([0-9a-fA-F]{8}-[0-9a-fA-F]{4}-[1-8][0-9a-fA-F]{3}-[89abAB][0-9a-fA-F]{3}-[0-9a-fA-F]{12}|00000000-0000-0000-0000-000000000000|ffffffff-ffff-ffff-ffff-ffffffffffff)$ persistent: nullable: true description: >- One shared volume, mounted at the same path on every node. type: object properties: volumeId: nullable: true description: >- Null on a quote for storage that will be created at launch. type: string format: uuid pattern: >- ^([0-9a-fA-F]{8}-[0-9a-fA-F]{4}-[1-8][0-9a-fA-F]{3}-[89abAB][0-9a-fA-F]{3}-[0-9a-fA-F]{12}|00000000-0000-0000-0000-000000000000|ffffffff-ffff-ffff-ffff-ffffffffffff)$ sizeGb: type: integer minimum: -9007199254740991 maximum: 9007199254740991 mountPath: type: string status: type: string usdPerHour: type: string pattern: ^\d+(?:\.\d{1,6})?$ description: >- Hourly storage price. Continues after the instance stops or is terminated. billsUntilDeleted: type: boolean enum: - true survivesStop: type: boolean enum: - true survivesTerminate: type: boolean enum: - true multiAttach: type: boolean enum: - false description: One instance at a time. required: - volumeId - sizeGb - mountPath - usdPerHour - billsUntilDeleted - survivesStop - survivesTerminate - multiAttach additionalProperties: false required: - rootGbPerNode - rootPersistence - volumeId - persistent additionalProperties: false price: type: object properties: usdPerHour: type: string pattern: ^\d+(?:\.\d{1,6})?$ description: >- Whole cluster: GPUs on every node + root disks. Inter-node networking is included. storageOnlyUsdPerHour: type: string pattern: ^\d+(?:\.\d{1,6})?$ description: >- What keeps billing after terminate: the shared persistent volume only. required: - usdPerHour - storageOnlyUsdPerHour additionalProperties: false capabilities: type: object properties: start: type: boolean enum: - false stop: type: boolean enum: - false restart: type: boolean enum: - false ssh: type: boolean logs: type: boolean persistentVolumes: type: boolean stopPreservesRootDisk: type: boolean enum: - false required: - start - stop - restart - ssh - logs - persistentVolumes - stopPreservesRootDisk additionalProperties: false recovery: type: object properties: policy: type: object properties: mode: type: string enum: - none - restart description: >- `none`: a resource that leaves `running` on its own is left for its owner (the default). `restart`: AI Reserve brings it back through the provider's own restart/start primitive, up to `maxAttempts` times per unhealthy episode, no more often than every `cooldownMinutes`. Recovery never relaunches on different hardware, never re-quotes and never changes the locked rate. maxAttempts: type: integer minimum: 1 maximum: 10 cooldownMinutes: type: integer minimum: 1 maximum: 120 required: - mode additionalProperties: false description: The owner's recovery policy for this resource. attempts: type: integer minimum: -9007199254740991 maximum: 9007199254740991 description: >- Attempts made in the current unhealthy episode. Reset to 0 once the resource is observed running again. maxAttempts: nullable: true description: >- The episode cap under the current policy; null when the policy is `none`. type: integer minimum: -9007199254740991 maximum: 9007199254740991 lastAttemptAt: nullable: true type: string format: date-time pattern: >- ^(?:(?:\d\d[2468][048]|\d\d[13579][26]|\d\d0[48]|[02468][048]00|[13579][26]00)-02-29|\d{4}-(?:(?:0[13578]|1[02])-(?:0[1-9]|[12]\d|3[01])|(?:0[469]|11)-(?:0[1-9]|[12]\d|30)|(?:02)-(?:0[1-9]|1\d|2[0-8])))T(?:(?:[01]\d|2[0-3]):[0-5]\d:[0-5]\d(?:\.\d+)?(?:Z|([+-](?:[01]\d|2[0-3]):[0-5]\d)))$ lastOutcome: nullable: true description: >- `recovering`: an attempt is in flight. `recovered`: the last attempt brought the resource back. `failed`: it did not; another may follow after the cooldown. `exhausted`: the cap was spent; `lastError` reads `recovery_exhausted` and the resource waits for its owner. type: string enum: - recovering - recovered - failed - exhausted required: - policy - attempts - maxAttempts - lastAttemptAt - lastOutcome additionalProperties: false description: >- Health recovery state. Billing is unchanged by recovery: the resource keeps accruing while an attempt runs. nodes: type: array items: type: object properties: rank: nullable: true description: >- `NODE_RANK`; 0 is the primary. Null until the provider assigns it. type: integer minimum: -9007199254740991 maximum: 9007199254740991 role: nullable: true description: >- `slurm_controller`, `slurm_compute`, `ray_head`, `ray_worker`, or null for bare nodes. type: string status: type: string enum: - requested - provisioning - starting - running - stopping - stopped - terminating - terminated - reconciling - failed overlayIp: nullable: true description: Address on the private interconnect. type: string sshAvailable: type: boolean required: - rank - role - status - overlayIp - sshAvailable additionalProperties: false description: >- A member node, read-only. Nodes cannot be added, removed, stopped or started individually. createdAt: type: string format: date-time pattern: >- ^(?:(?:\d\d[2468][048]|\d\d[13579][26]|\d\d0[48]|[02468][048]00|[13579][26]00)-02-29|\d{4}-(?:(?:0[13578]|1[02])-(?:0[1-9]|[12]\d|3[01])|(?:0[469]|11)-(?:0[1-9]|[12]\d|30)|(?:02)-(?:0[1-9]|1\d|2[0-8])))T(?:(?:[01]\d|2[0-3]):[0-5]\d:[0-5]\d(?:\.\d+)?(?:Z|([+-](?:[01]\d|2[0-3]):[0-5]\d)))$ readyAt: nullable: true description: >- When every node was first verified running; the billing clock start. type: string format: date-time pattern: >- ^(?:(?:\d\d[2468][048]|\d\d[13579][26]|\d\d0[48]|[02468][048]00|[13579][26]00)-02-29|\d{4}-(?:(?:0[13578]|1[02])-(?:0[1-9]|[12]\d|3[01])|(?:0[469]|11)-(?:0[1-9]|[12]\d|30)|(?:02)-(?:0[1-9]|1\d|2[0-8])))T(?:(?:[01]\d|2[0-3]):[0-5]\d:[0-5]\d(?:\.\d+)?(?:Z|([+-](?:[01]\d|2[0-3]):[0-5]\d)))$ lastError: nullable: true type: string required: - id - name - status - desiredState - accelerator - topology - runtime - location - storage - price - capabilities - recovery - nodes - createdAt - readyAt - lastError additionalProperties: false description: >- A provider-hidden multi-node GPU cluster. Provider placement identifiers are intentionally omitted. nextCursor: description: Pass as `?cursor=` to fetch the next page. type: string required: - data additionalProperties: false '400': description: Invalid request, missing Idempotency-Key, or schema violation. content: application/json: schema: $ref: '#/components/schemas/ComputeError' '401': description: Missing or invalid API key. content: application/json: schema: $ref: '#/components/schemas/ComputeError' '403': description: Key lacks the required compute access (`read` or `manage`). content: application/json: schema: $ref: '#/components/schemas/ComputeError' '404': description: Resource not found or owned by another organization. content: application/json: schema: $ref: '#/components/schemas/ComputeError' security: - bearerAuth: [] - apiKeyAuth: [] components: schemas: ComputeError: type: object properties: error: type: object properties: message: type: string type: type: string enum: - invalid_request_error - authentication_error - permission_error - server_error param: nullable: true type: string code: type: string description: >- Machine-readable Compute error code, e.g. `quote_expired`, `price_changed`, `operation_conflict`, `no_capacity`, `volume_in_use`, `insufficient_funds`, `compute_access_required`, `not_found`. details: description: >- Machine-readable context for some codes. For `no_capacity` see `ComputeNoCapacityDetails`. type: object additionalProperties: {} required: - message - type - param - code additionalProperties: false required: - error additionalProperties: false description: OpenAI-shaped error envelope returned on every 4xx/5xx. securitySchemes: bearerAuth: type: http scheme: bearer description: >- Your AI Reserve API key (aireserve_api_…) from the API Keys page in the portal (https://portal.aireserve.com/keys). apiKeyAuth: type: apiKey in: header name: x-api-key description: The same API key sent as an `x-api-key` header. ```` This documentation is built and hosted on [Mintlify](https://mintlify.com), a developer documentation platform.