> ## Documentation Index > Fetch the complete documentation index at: https://docs.together.ai/llms.txt > Use this file to discover all available pages before exploring further. # List all GPU clusters > List all GPU clusters. ## OpenAPI ````yaml GET /compute/clusters openapi: 3.1.0 info: title: Together APIs description: The Together REST API. See https://docs.together.ai for more details. version: 2.0.0 termsOfService: https://www.together.ai/terms-of-service contact: name: Together Support url: https://www.together.ai/contact license: name: MIT url: https://github.com/togethercomputer/openapi/blob/main/LICENSE servers: - url: https://api.together.ai/v1 security: - bearerAuth: [] paths: /compute/clusters: get: tags: - GPUClusterService summary: List all GPU clusters description: List all GPU clusters. operationId: GPUClusterService_List parameters: - name: project_id in: query schema: description: >- Optional UMS project ID to filter clusters by. When set, only clusters belonging to this project are returned. The caller must be a member of the project; otherwise the result set will be empty. type: string responses: '200': description: OK content: application/json: schema: $ref: '#/components/schemas/GPUClusters' x-codeSamples: - lang: Python label: Together AI SDK (v2) source: | from together import Together import os client = Together( api_key=os.environ.get("TOGETHER_API_KEY"), ) response = client.beta.clusters.list() print(response.clusters) - lang: TypeScript label: Together AI SDK (TypeScript) source: | import Together from "together-ai"; const client = new Together({ apiKey: process.env.TOGETHER_API_KEY, }); const response = await client.beta.clusters.list(); console.log(response.clusters); - lang: JavaScript label: Together AI SDK (JavaScript) source: | import Together from "together-ai"; const client = new Together({ apiKey: process.env.TOGETHER_API_KEY, }); const response = await client.beta.clusters.list(); console.log(response.clusters); - lang: Shell label: CLI source: tg beta clusters list components: schemas: GPUClusters: type: object required: - clusters properties: clusters: type: array items: $ref: '#/components/schemas/GPUClusterInfo' GPUClusterInfo: type: object required: - cluster_id - cluster_type - region - gpu_type - cluster_name - cuda_version - nvidia_driver_version - volumes - status - control_plane_nodes - gpu_worker_nodes - kube_config - num_gpus - project_id - num_cpu_workers - phase_transitions - desired_preemptible_gpus - allocated_preemptible_gpus - num_capacity_pool_gpus - num_reserved_gpus - billing_type - add_ons properties: cluster_id: type: string cluster_type: description: Type of cluster. enum: - KUBERNETES - SLURM region: type: string gpu_type: enum: - H100_SXM - H200_SXM - RTX_6000_PCI - L40_PCIE - B200_SXM - H100_SXM_INF cluster_name: type: string duration_hours: type: integer volumes: type: array items: $ref: '#/components/schemas/GPUClusterVolume' status: description: Current status of the GPU cluster. enum: - WaitingForControlPlaneNodes - WaitingForDataPlaneNodes - WaitingForSubnet - WaitingForSharedVolume - InstallingDrivers - RunningAcceptanceTests - Paused - OnDemandComputePaused - Ready - Degraded - Deleting control_plane_nodes: type: array items: $ref: '#/components/schemas/GPUClusterControlPlaneNode' gpu_worker_nodes: type: array items: $ref: '#/components/schemas/GPUClusterGPUWorkerNode' kube_config: type: string num_gpus: type: integer format: int32 slurm_shm_size_gib: type: integer capacity_pool_id: type: string reservation_start_time: type: string format: date-time reservation_end_time: type: string format: date-time install_traefik: type: boolean cuda_version: type: string nvidia_driver_version: type: string created_at: type: string format: date-time oidc_config: $ref: '#/components/schemas/OIDCConfig' project_id: type: string cluster_config: $ref: '#/components/schemas/InstanceClusterConfig' num_cpu_workers: type: integer description: Number of CPU-only worker nodes in the cluster. format: int32 phase_transitions: type: array items: $ref: '#/components/schemas/ClusterPhaseTransition' description: Cluster-level phase transition history. desired_preemptible_gpus: type: integer description: >- Customer's requested number of preemptible GPUs. Set on cluster create or update; persists until changed. format: int32 allocated_preemptible_gpus: type: integer description: >- Actual number of preemptible GPUs currently allocated to the cluster. Updated asynchronously by the fulfillment and reclamation workers; may be less than desired_preemptible_gpus when capacity is constrained. format: int32 billing_type: enum: - RESERVED - ON_DEMAND - SCHEDULED_CAPACITY type: string description: >- Billing type for the cluster (RESERVED, ON_DEMAND, or SCHEDULED_CAPACITY). add_ons: type: array items: $ref: '#/components/schemas/AddOnInfo' description: >- Enabled add-ons on this cluster. Only add-ons with enabled=true in their config are returned. machine_cluster_id: type: string description: ID of the machine cluster backing this GPU cluster. first_ready_at: type: string description: Timestamp when the cluster first reached the Ready phase. format: date-time is_in_substrate: type: boolean description: Whether the cluster is managed inside a substrate environment. control_plane_ready: type: boolean description: Whether the control plane is currently ready. ums_project_id: type: string description: UMS project ID associated with this cluster. ums_org_id: type: string description: UMS organization ID associated with this cluster. os_image: type: string description: Data-volume image name for GPU worker nodes. nvidia_driver_version_id: type: string description: >- Internal NVIDIA version ID for this cluster's driver and CUDA combination. num_capacity_pool_gpus: type: integer description: >- Number of GPUs to draw from a capacity pool. A component of the overall num_gpus, alongside num_reserved_gpus. format: int32 num_reserved_gpus: type: integer description: >- Number of prepaid reserved GPUs for this cluster. A component of the overall num_gpus, alongside num_capacity_pool_gpus. format: int32 deleted_gpu_worker_nodes: type: array items: $ref: '#/components/schemas/GPUClusterGPUWorkerNode' description: >- GPU worker nodes retained after they left the live data plane. These are separate from gpu_worker_nodes and must not be counted as live capacity. node_lifecycle_events: type: array items: $ref: '#/components/schemas/GPUClusterNodeLifecycleEvent' description: >- Recent node lifecycle events such as scale-up, scale-down, and preemption. Combine these with live and deleted node lists to render the cluster timeline. GPUClusterVolume: type: object required: - volume_id - volume_name - size_tib - status properties: volume_id: description: ID of the volume. type: string volume_name: type: string description: User provided name of the volume. size_tib: type: integer description: Size of the volume in TiB. status: type: string description: Current status of the volume. GPUClusterControlPlaneNode: type: object required: - node_id - status - host_name - num_cpu_cores - memory_gib - network - phase_transitions properties: node_id: type: string status: type: string host_name: type: string num_cpu_cores: type: integer memory_gib: type: number format: float network: type: string phase_transitions: type: array items: $ref: '#/components/schemas/NodePhaseTransition' description: Phase transition history for this control plane node. public_ipv4: type: string description: Public IPv4 address of the control plane node. GPUClusterGPUWorkerNode: type: object required: - node_id - status - host_name - num_cpu_cores - num_gpus - memory_gib - networks - phase_transitions properties: node_id: type: string status: type: string host_name: type: string num_cpu_cores: type: integer num_gpus: type: integer memory_gib: type: number format: float networks: type: array items: type: string instance_id: type: string latest_remediation: $ref: '#/components/schemas/Remediation' slurm_worker_hostname: type: string phase_transitions: type: array items: $ref: '#/components/schemas/NodePhaseTransition' description: Phase transition history for this GPU worker node. marked_for_deletion: type: boolean description: Whether this node is marked for deletion by the operator. public_ipv4: type: string description: Public IPv4 address of the GPU worker node. ib_hca_type: type: string description: InfiniBand HCA type. ib_hca_count: type: integer description: Number of InfiniBand HCAs. nvswitch_count: type: integer description: Number of NVSwitches. nvswitch_type: type: string description: NVSwitch type. ephemeral_storage: type: string description: Ephemeral storage size, such as 1Ti. auto_remediation_enabled: type: boolean description: Whether auto-remediation is enabled for this node's instance. deleted_at: type: string description: >- Timestamp when the node left the live data plane. Only set for deleted_gpu_worker_nodes. format: date-time OIDCConfig: type: object required: - issuer_url - client_id - username_claim - username_prefix - group_claim - group_prefix properties: issuer_url: type: string description: >- OIDC issuer URL for authentication. For example, https://accounts.google.com client_id: type: string description: OIDC client ID for authentication. username_claim: type: string description: JWT claim to use as the username. For example, 'sub' or 'email' username_prefix: type: string description: >- Prefix to add to the username claim to form the final username. For example, 'oidc:' group_claim: type: string description: JWT claim to use for user groups. For example, 'groups' group_prefix: type: string description: >- Prefix to add to the group claim to form the final group name. For example, 'oidc:' ca_cert: type: string description: >- CA certificate in PEM format to validate the OIDC issuer's TLS certificate. This field is optional but recommended if the issuer uses a private CA or self-signed certificate. InstanceClusterConfig: type: object required: - load_balancer properties: load_balancer: enum: - NONE - TRAEFIK - NGINX - ISTIO type: string kubernetes_dashboard_enabled: type: boolean jumphost_enabled: type: boolean slurm_startup_scripts: $ref: '#/components/schemas/SlurmStartupScripts' ingress: $ref: '#/components/schemas/ClusterIngressConfig' observability: $ref: '#/components/schemas/ObservabilityConfig' gpu_operator_version: type: string description: >- NVIDIA GPU Operator chart/version for the tenant cluster (e.g. v24.6.2). When omitted, a service default is applied. network_operator_version: type: string description: >- NVIDIA Network Operator chart/version for the tenant cluster (e.g. v24.7.0). When omitted, a service default is applied. ssh_ca_enabled: type: boolean description: >- Whether this cluster uses a per-cluster SSH certificate authority for OIDC-signed SSH access. ClusterPhaseTransition: type: object required: - phase - transition_time properties: phase: enum: - CLUSTER_PHASE_QUEUED - CLUSTER_PHASE_SCHEDULED - CLUSTER_PHASE_WAITING_FOR_CONTROL_PLANE_NODES - CLUSTER_PHASE_WAITING_FOR_DATA_PLANE_NODES - CLUSTER_PHASE_WAITING_FOR_SUBNET - CLUSTER_PHASE_WAITING_FOR_SHARED_VOLUME - CLUSTER_PHASE_WAITING_FOR_AUTO_SCALER - CLUSTER_PHASE_INSTALLING_DRIVERS - CLUSTER_PHASE_RUNNING_ACCEPTANCE_TESTS - CLUSTER_PHASE_ACCEPTANCE_TESTS_FAILED - CLUSTER_PHASE_RUNNING_NCCL_TESTS - CLUSTER_PHASE_NCCL_TESTS_FAILED - CLUSTER_PHASE_READY - CLUSTER_PHASE_PAUSED - CLUSTER_PHASE_ON_DEMAND_COMPUTE_PAUSED - CLUSTER_PHASE_DEGRADED - CLUSTER_PHASE_DELETING type: string description: Cluster phase. transition_time: type: string description: Timestamp when the phase transition occurred. format: date-time AddOnInfo: type: object required: - name - add_on_type - config - state properties: name: type: string add_on_type: type: string config: $ref: '#/components/schemas/AddOnConfig' state: $ref: '#/components/schemas/AddOnState' description: AddOnInfo is returned in cluster responses and add-on CRUD operations. GPUClusterNodeLifecycleEvent: type: object description: Node lifecycle event included in a GPU cluster timeline. required: - node_id - reason - message - timestamp properties: node_id: type: string description: Tenant node name this lifecycle event applies to. reason: type: string description: >- Lifecycle event reason, for example TogetherScaledUp, TogetherScaledDown, or TogetherPreempted. message: type: string description: Human-readable lifecycle event message. timestamp: type: string description: Event timestamp. format: date-time NodePhaseTransition: type: object required: - phase - transition_time properties: phase: enum: - NODE_PHASE_PENDING - NODE_PHASE_SCHEDULING - NODE_PHASE_BOOTING - NODE_PHASE_BOOTSTRAPPING - NODE_PHASE_RUNNING - NODE_PHASE_SUCCEEDED - NODE_PHASE_FAILED - NODE_PHASE_PAUSED type: string description: Node phase. transition_time: type: string description: Timestamp when the phase transition occurred. format: date-time Remediation: type: object required: - id - cluster_id - instance_id - mode - trigger - state properties: id: readOnly: true type: string cluster_id: readOnly: true type: string instance_id: readOnly: true type: string mode: enum: - REMEDIATION_MODE_VM_ONLY - REMEDIATION_MODE_HOST_AWARE - REMEDIATION_MODE_EVICT_WITHOUT_REPLACEMENT - REMEDIATION_MODE_REBOOT_VM type: string description: > Remediation mode specifies how the remediation should be performed. - `REMEDIATION_MODE_VM_ONLY`: Deletes the VM and provisions a new one on any available host. - `REMEDIATION_MODE_HOST_AWARE`: Cordons the host, deletes the VM, and provisions a new one on a different host. trigger: readOnly: true enum: - REMEDIATION_TRIGGER_MANUAL - REMEDIATION_TRIGGER_AUTOMATED type: string description: > RemediationTrigger specifies how the remediation was triggered. - `REMEDIATION_TRIGGER_MANUAL`: A user-initiated remediation (either via web UI or API call). - `REMEDIATION_TRIGGER_AUTOMATED`: A system-initiated remediation that requires approval. state: readOnly: true enum: - PENDING_APPROVAL - PENDING - RUNNING - SUCCEEDED - FAILED - CANCELLED - AUTO_RESOLVED type: string description: > RemediationState represents the lifecycle state of a remediation. - `PENDING_APPROVAL`: Awaiting approval before processing can begin. - `PENDING`: Approved and queued for processing. - `RUNNING`: Actively being processed. - `SUCCEEDED`: Successfully completed. - `FAILED`: Failed with an error. - `CANCELLED`: Cancelled by user or system. - `AUTO_RESOLVED`: The underlying issue was automatically resolved before processing. reason: type: string description: User-provided reason for the remediation. active_health_check_run_id: type: string description: Active health check run ID (UUID) that triggered this remediation. readOnly: true passive_health_check_event_id: type: string description: Passive health check event ID that triggered this remediation. readOnly: true requested_by: readOnly: true type: string description: Who requested the remediation. create_time: type: string description: When the remediation was created. format: date-time readOnly: true reviewed_by: type: string description: Who reviewed the remediation. readOnly: true review_time: type: string format: date-time description: When the remediation was reviewed. readOnly: true review_comment: readOnly: true type: string description: Review comment. start_time: type: string format: date-time description: When processing started. readOnly: true end_time: readOnly: true type: string description: When the remediation completed. format: date-time error_message: readOnly: true type: string description: Error message if the remediation failed. update_time: readOnly: true type: string description: When the remediation was last updated. format: date-time instance_name: readOnly: true type: string description: Display name of the targeted instance. description: >- Remediation represents a node remediation request for an instance. An instance can have multiple remediations over time (e.g., failed attempts followed by retries). SlurmStartupScripts: type: object properties: worker_prolog: type: string description: Slurm worker node prolog script. worker_epilog: type: string description: Slurm worker node epilog script. controller_prolog: type: string description: Slurm controller prolog script. controller_epilog: type: string description: Slurm controller epilog script. login_init_script: type: string description: Script run on Slurm login node init. nodeset_init_script: type: string description: Script run on Slurm nodeset init. extra_slurm_conf: type: string description: Additional slurm.conf fragments. description: >- SlurmStartupScripts carries optional Slurm lifecycle scripts (prolog/epilog, init, extra conf). ClusterIngressConfig: type: object properties: enabled: type: boolean ObservabilityConfig: type: object properties: enabled: type: boolean AddOnConfig: type: object properties: dashboard: $ref: '#/components/schemas/DashboardConfig' ingress: $ref: '#/components/schemas/IngressConfig' torchpass: $ref: '#/components/schemas/TorchpassConfig' description: Configuration for the Model Aware TorchPass add-on. description: Configuration for a cluster add-on. AddOnState: type: object properties: dashboard: $ref: '#/components/schemas/DashboardState' ingress: $ref: '#/components/schemas/IngressState' torchpass: $ref: '#/components/schemas/TorchpassState' description: State for the Model Aware TorchPass add-on. description: State for a cluster add-on. DashboardConfig: type: object properties: enabled: type: boolean IngressConfig: type: object properties: enabled: type: boolean TorchpassConfig: type: object properties: enabled: type: boolean description: Whether to enable the Model Aware TorchPass add-on. description: Configuration for the Model Aware TorchPass cluster add-on. DashboardState: type: object properties: {} additionalProperties: false x-stainless-empty-object: true IngressState: type: object properties: {} additionalProperties: false x-stainless-empty-object: true TorchpassState: type: object properties: {} additionalProperties: false x-stainless-empty-object: true description: Runtime state for the Model Aware TorchPass cluster add-on. securitySchemes: bearerAuth: type: http scheme: bearer x-bearer-format: bearer x-default: default ````