v3

OpenAPI 3.1.0MIT2026-07-31192456807.8 KB

GPUClusterService

Create a GPU cluster

Create an Instant Cluster on Together's high-performance GPU clusters. With features like on-demand scaling, long-lived resizable high-bandwidth shared DC-local storage, Kubernetes and Slurm cluster flavors, a REST API, and Terraform support, you can run workloads flexibly without complex infrastructure management.

post/compute/clusters

Request body

cluster_type'KUBERNETES' | 'SLURM'

Type of cluster to create.

regionstring required

Region to create the GPU cluster in. Usable regions can be found from client.clusters.list_regions()

Type of GPU to use in the cluster

num_gpusinteger required

Number of GPUs to allocate in the cluster. This must be multiple of 8. For example, 8, 16 or 24

cluster_namestring required

Name of the GPU cluster.

duration_daysinteger

Duration in days to keep the cluster running.

volume_idstring

ID of an existing volume to use with the cluster creation.

billing_type'RESERVED' | 'ON_DEMAND' | 'SCHEDULED_CAPACITY' required

RESERVED billing types allow you to specify the duration of the cluster reservation via the duration_days field. ON_DEMAND billing types will give you ownership of the cluster until you delete it. SCHEDULED_CAPACITY billing types allow you to reserve capacity for a scheduled time window. You must specify the reservation_start_time and reservation_end_time with this request.

auto_scaledboolean

Whether GPU cluster should be auto-scaled based on the workload. By default, it is not auto-scaled.

auto_scale_max_gpusinteger

Maximum number of GPUs to which the cluster can be auto-scaled up. This field is required if auto_scaled is true.

slurm_shm_size_gibinteger

Shared memory size in GiB for Slurm cluster. This field is required if cluster_type is SLURM.

capacity_pool_idstring

ID of the capacity pool to use for the cluster. This field is optional and only applicable if the cluster is created from a capacity pool.

reservation_start_timestring date-time

Reservation start time of the cluster. This field is required for SCHEDULED billing to specify the reservation start time for the cluster. If not provided, the cluster provisions immediately.

reservation_end_timestring date-time

Reservation end time of the cluster. This field is required for SCHEDULED billing to specify the reservation end time for the cluster.

install_traefikboolean

Whether to install Traefik ingress controller in the cluster. This field is only applicable for Kubernetes clusters and is false by default.

cuda_versionstring required

CUDA version for this cluster. For example, 12.5

nvidia_driver_versionstring required

Nvidia driver version for this cluster. For example, 550. Only some combination of cuda_version and nvidia_driver_version are supported.

slurm_imagestring

Custom Slurm image for Slurm clusters.

project_idstring

Project ID for the cluster. If not set, the project from the request context is used.

num_capacity_pool_gpusinteger

Number of GPUs to allocate from the capacity pool. Must be a multiple of 8 and not exceed num_gpus.

auto_scaleboolean

Whether to enable auto-scaling for the cluster. If true, the cluster will automatically scale the number of GPU worker nodes between num_gpus and auto_scale_max_gpus based on the workload.

num_preemptible_gpusinteger

Number of preemptible GPUs to request alongside on-demand capacity. Must be a multiple of 8. Preemptible nodes are cheaper but may be reclaimed when on-demand capacity is needed elsewhere; the system fulfills this asynchronously and surfaces the actual count in allocated_preemptible_gpus.

num_reserved_gpusinteger

Number of prepaid (PLG) reserved GPUs for this cluster. When omitted for RESERVED billing on create, the server defaults this to num_gpus.

Response

cluster_idstring required

cluster_type'KUBERNETES' | 'SLURM' required

Type of cluster.

regionstring required

cluster_namestring required

duration_hoursinteger

Current status of the GPU cluster.

kube_configstring required

num_gpusinteger required

slurm_shm_size_gibinteger

capacity_pool_idstring

reservation_start_timestring date-time

reservation_end_timestring date-time

install_traefikboolean

cuda_versionstring required

nvidia_driver_versionstring required

created_atstring date-time

project_idstring required

num_cpu_workersinteger required

Number of CPU-only worker nodes in the cluster.

desired_preemptible_gpusinteger required

Customer's requested number of preemptible GPUs. Set on cluster create or update; persists until changed.

allocated_preemptible_gpusinteger required

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.

billing_type'RESERVED' | 'ON_DEMAND' | 'SCHEDULED_CAPACITY' required

Billing type for the cluster (RESERVED, ON_DEMAND, or SCHEDULED_CAPACITY).

machine_cluster_idstring

ID of the machine cluster backing this GPU cluster.

first_ready_atstring date-time

Timestamp when the cluster first reached the Ready phase.

is_in_substrateboolean

Whether the cluster is managed inside a substrate environment.

control_plane_readyboolean

Whether the control plane is currently ready.

ums_project_idstring

UMS project ID associated with this cluster.

ums_org_idstring

UMS organization ID associated with this cluster.

os_imagestring

Data-volume image name for GPU worker nodes.

nvidia_driver_version_idstring

Internal NVIDIA version ID for this cluster's driver and CUDA combination.

num_capacity_pool_gpusinteger required

Number of GPUs to draw from a capacity pool. A component of the overall num_gpus, alongside num_reserved_gpus.

num_reserved_gpusinteger required

Number of prepaid reserved GPUs for this cluster. A component of the overall num_gpus, alongside num_capacity_pool_gpus.