> ## Documentation Index
> Fetch the complete documentation index at: https://docs.ornn.com/llms.txt
> Use this file to discover all available pages before exploring further.

# List clusters and workers

> Returns up to 500 of your organization's newest Kubernetes and Slurm clusters, each with its workers. A cluster leaves this list when its teardown finishes. There is no cursor and no customer GET-by-ID route. Select one cluster by controller.id. Your organization runs at most one live cluster of each kind, so after a create times out, the live cluster of that kind is the one it created. Poll this resource to follow launch, worker, and teardown progress. controller.state is active once every launch worker has joined and access has been issued; it does not prove Kubernetes Node readiness or GPU capacity. Because the list is bounded, confirm that a specific cluster's teardown finished with getClusterAccess, which then returns 404 cluster_not_found.

CLI equivalent, after `ornn login`:

```bash theme={null}
ornn clusters list
ornn clusters show CLUSTER_ID
ornn clusters wait CLUSTER_ID --timeout 60m
```


## OpenAPI

````yaml openapi.yaml GET /v1/orchestrator/controllers
openapi: 3.1.0
info:
  title: Ornn compute API
  version: 1.0.0
  description: >-
    Customer HTTP API for Ornn GPU capacity. It covers reserved capacity and
    nodes, VM and Bare Metal access, Kubernetes and Slurm clusters, SSH keys,
    storage volumes and GitHub repositories, private networks, monitoring,
    buying and selling capacity (Reserve, Market, Spot, and Relist), and
    billing. API keys are scoped to one organization and act with their
    creator's access there; account, team, and API-key management stay in the
    console. Most operations require an approved organization. See
    https://docs.ornn.com/api-keys to create a key and
    https://docs.ornn.com/guides/kubernetes-api for an end-to-end Kubernetes
    integration. Examples use fictional IDs and credentials. The info.version
    field identifies the contract revision, not a shared API path version.
  contact:
    email: support@ornn.com
servers:
  - url: https://api.ornn.com
    description: Production
security:
  - OrnnApiKey: []
tags:
  - name: Authentication
  - name: Reservations
  - name: GPU nodes
  - name: Clusters
  - name: Workers
  - name: Virtual machines
    description: >-
      Choose a VM disk, launch VM access on a reservation, and read each VM's
      status, launch progress, and SSH connection details.
  - name: Bare Metal
    description: >-
      Launch Bare Metal access on a reservation, read a host's readiness and SSH
      connection details, and reboot or hard reset it.
  - name: SSH keys
    description: >-
      Register public keys for your organization, choose which keys a VM or Bare
      Metal reservation uses, and queue key delivery to machines. Slurm clusters
      take organization key IDs at launch. Kubernetes API access does not use
      SSH keys.
  - name: Reserve
    description: >-
      Browse reserved-capacity listings and their terms, and post, cancel, or
      accept offers. Reserve listings are visible to approved organizations.
  - name: Market
    description: >-
      Browse relisted capacity and buy windows at the asking price, paid up
      front. Open to every member of your organization.
  - name: Spot
    description: >-
      Hourly order books for VMs with 1, 2, 4, or 8 GPUs on one node: read
      books, trades, and quotes, place and cancel bids, and follow fills.
  - name: Relist
    description: >-
      Sell whole nodes from a reservation you hold at your asking price, and
      manage those listings.
  - name: Storage
    description: >-
      Managed volumes, their files, and GitHub repository pulls. Volumes belong
      to the API key's creator in the key's organization.
  - name: Networks
    description: >-
      Organization private networks and the WireGuard configs you use to reach
      private machines and clusters.
  - name: Monitoring
    description: >-
      Machine telemetry and console logs for capacity your organization holds.
      Reads are limited to your reservation window.
  - name: Billing
    description: >-
      Invoices, billing summary, usage cost, Ornn credits, and account
      statements. Saving a card and paying invoices stay in the console.
externalDocs:
  description: REST integration walkthrough
  url: >-
    https://docs.ornn.com/guides/kubernetes-access#provision-and-manage-through-rest
paths:
  /v1/orchestrator/controllers:
    get:
      tags:
        - Clusters
      summary: List clusters and workers
      description: >-
        Returns up to 500 of your organization's newest Kubernetes and Slurm
        clusters, each with its workers. A cluster leaves this list when its
        teardown finishes. There is no cursor and no customer GET-by-ID route.
        Select one cluster by controller.id. Your organization runs at most one
        live cluster of each kind, so after a create times out, the live cluster
        of that kind is the one it created. Poll this resource to follow launch,
        worker, and teardown progress. controller.state is active once every
        launch worker has joined and access has been issued; it does not prove
        Kubernetes Node readiness or GPU capacity. Because the list is bounded,
        confirm that a specific cluster's teardown finished with
        getClusterAccess, which then returns 404 cluster_not_found.
      operationId: listClusters
      parameters:
        - name: kind
          in: query
          required: false
          description: Filter by cluster type.
          schema:
            type: string
            enum:
              - kubernetes
              - slurm
          example: kubernetes
      responses:
        '200':
          description: >-
            Clusters with their worker memberships. The example shows an active
            Kubernetes cluster.
          content:
            application/json:
              schema:
                $ref: '#/components/schemas/ClusterList'
              example:
                controllers:
                  - controller:
                      id: 44444444-4444-4444-8444-444444444444
                      kind: kubernetes
                      state: active
                      network_mode: public
                      network_id: null
                      endpoint: https://cluster.example.com:6443
                      credential_state: active
                      metadata:
                        namespace: k8s-22222222-2222-4222-8222-222222222222
                      backend_metadata:
                        kubernetes_launch:
                          reservation_id: 11111111-1111-4111-8111-111111111111
                      progress:
                        stages:
                          - key: create_plane
                            label: Create the control plane
                            status: completed
                            detail: null
                          - key: prepare_hosts
                            label: Prepare the hosts
                            status: completed
                            detail: null
                          - key: join_workers
                            label: Join the workers
                            status: completed
                            detail: null
                          - key: apply_plane
                            label: Apply the control plane
                            status: completed
                            detail: null
                          - key: issue_access
                            label: Issue access
                            status: completed
                            detail: null
                      created_at: '2026-10-14T12:00:00Z'
                      updated_at: '2026-10-14T12:20:00Z'
                    nodes:
                      - node_id: 33333333-3333-4333-8333-333333333333
                        controller_id: 44444444-4444-4444-8444-444444444444
                        reservation_id: 11111111-1111-4111-8111-111111111111
                        role: worker
                        state: ready
                        gpu_count: 8
                        linux_username: tenant
                        ssh_port: 22
        '401':
          $ref: '#/components/responses/Unauthorized'
        '403':
          $ref: '#/components/responses/Forbidden'
        default:
          $ref: '#/components/responses/Error'
components:
  schemas:
    ClusterList:
      type: object
      required:
        - controllers
      properties:
        controllers:
          type: array
          items:
            type: object
            required:
              - controller
              - nodes
            properties:
              controller:
                $ref: '#/components/schemas/Cluster'
              nodes:
                type: array
                items:
                  $ref: '#/components/schemas/Worker'
    Cluster:
      type: object
      required:
        - id
        - kind
        - state
        - network_mode
        - credential_state
      properties:
        id:
          type: string
          format: uuid
        kind:
          type: string
          enum:
            - kubernetes
            - slurm
        state:
          type: string
          description: >-
            pending or provisioning while launching; active once every launch
            worker has joined and access has been issued; failed when a launch
            or teardown did not finish; deleting during teardown. A cluster
            whose teardown finished is no longer listed. Treat unrecognized
            values as not ready.
        network_mode:
          type: string
          enum:
            - public
            - private
        network_id:
          type:
            - string
            - 'null'
          format: uuid
          description: >-
            The dedicated organization network for a private cluster, or null
            for the shared default.
        endpoint:
          type:
            - string
            - 'null'
          description: >-
            Kubernetes API server URL, or the Slurm login host, while state is
            active; otherwise null.
        credential_state:
          type: string
          description: >-
            pending until access is issued, then active. Issued access does not
            prove Kubernetes worker or GPU readiness.
        metadata:
          type:
            - object
            - 'null'
          properties:
            namespace:
              type: string
              description: The namespace Ornn configured for your workloads.
        backend_metadata:
          type:
            - object
            - 'null'
          description: >-
            The reservation the cluster launched on, under kubernetes_launch or
            slurm_launch.
          properties:
            kubernetes_launch:
              type: object
              properties:
                reservation_id:
                  type: string
                  format: uuid
            slurm_launch:
              type: object
              properties:
                reservation_id:
                  type: string
                  format: uuid
        progress:
          anyOf:
            - $ref: '#/components/schemas/Progress'
            - type: 'null'
        created_at:
          type: string
          format: date-time
        updated_at:
          type: string
          format: date-time
    Worker:
      type: object
      required:
        - node_id
        - role
        - gpu_count
      properties:
        node_id:
          type: string
          format: uuid
        controller_id:
          type:
            - string
            - 'null'
          format: uuid
        reservation_id:
          type:
            - string
            - 'null'
          format: uuid
        role:
          type: string
          description: Always worker. Ornn runs the control plane separately.
        state:
          type:
            - string
            - 'null'
          description: >-
            joining while the host joins; ready once it has joined; join_failed
            if it could not join; draining after a removal request;
            cleanup_failed if removal cleanup did not finish. Can be null. A
            host being prepared after an add request is not listed until
            preparation finishes. For Kubernetes, verify Node readiness and
            allocatable GPUs through the cluster API.
        gpu_count:
          type: integer
          description: GPUs on this host.
        linux_username:
          type:
            - string
            - 'null'
        ssh_port:
          type:
            - integer
            - 'null'
    Error:
      type: object
      properties:
        code:
          type: string
        detail:
          oneOf:
            - type: string
            - type: object
              required:
                - code
                - message
              properties:
                code:
                  type: string
                message:
                  type: string
    Progress:
      type: object
      description: >-
        Stages of the latest launch or teardown. Launch stages are create_plane,
        prepare_hosts, join_workers, apply_plane, and issue_access. Teardown
        stages include workers and the control-plane stage (namespace for
        Kubernetes, stack for Slurm), plus nodes or storage when those steps
        fail.
      properties:
        stages:
          type: array
          items:
            type: object
            properties:
              key:
                type: string
                description: Stable stage identifier.
              label:
                type: string
                description: Display label for the stage.
              status:
                type: string
                enum:
                  - pending
                  - running
                  - completed
                  - failed
              detail:
                type:
                  - string
                  - 'null'
                description: Failure reason or worker confirmation count, when available.
  responses:
    Unauthorized:
      description: >-
        The credential is missing, invalid, revoked, or no longer belongs to a
        current organization member. Check the HTTP status before parsing the
        body.
      content:
        application/json:
          schema:
            $ref: '#/components/schemas/Error'
    Forbidden:
      description: >-
        The credential lacks access to this operation, or the organization
        requires approval. An API key does not bypass these checks.
      content:
        application/json:
          schema:
            $ref: '#/components/schemas/Error'
    Error:
      description: >-
        Unsuccessful request. Check HTTP status first. Errors may have
        detail.code/detail.message, a string detail and optional top-level code,
        or an empty/non-JSON body. 401: invalid credential; 403: access or
        approval required; 404: not visible or credentials not ready; 409:
        lifecycle conflict; 429: back off; 5xx: service failure. Inspect current
        state before retrying mutations.
      content:
        application/json:
          schema:
            $ref: '#/components/schemas/Error'
  securitySchemes:
    OrnnApiKey:
      type: http
      scheme: bearer
      bearerFormat: ornn_sk_...
      description: >-
        Create an organization API key in Account Settings > Developer. Do not
        send this key to the Kubernetes API server.

````

This documentation is built and hosted on [Mintlify](https://mintlify.com), a developer documentation platform.