Create a GPU cluster

POST

compute

clusters

Together AI SDK (Python)

from together import Together

client = Together()

response = client.clusters.create(
  cluster_name="my-gpu-cluster",
  region="us-central-8",
  gpu_type="H100_SXM",
  num_gpus=8,
  nvidia_driver_version="560",
  cuda_version="12.6",
  billing_type="ON_DEMAND",
)

print(response.cluster_id)

import Together from "together-ai";

const client = new Together();

const response = await client.clusters.create({
  cluster_name: "my-gpu-cluster",
  region: "us-central-8",
  gpu_type: "H100_SXM",
  num_gpus: 8,
  nvidia_driver_version: "560",
  cuda_version: "12.6",
  billing_type: "ON_DEMAND",
});

console.log(response.cluster_id)

import Together from "together-ai";

const client = new Together();

const response = await client.clusters.create({
  cluster_name: "my-gpu-cluster",
  region: "us-central-8",
  gpu_type: "H100_SXM",
  num_gpus: 8,
  nvidia_driver_version: "560",
  cuda_version: "12.6",
  billing_type: "ON_DEMAND",
});

console.log(response.cluster_id)

tg clusters create \
  --name my-gpu-cluster \
  --region us-central-8 \
  --gpu-type H100_SXM \
  --cluster-type KUBERNETES \
  --num-gpus 8 \
  --billing-type ON_DEMAND \
  --nvidia-driver-version 560 \
  --cuda-version 12.6

<?php

$curl = curl_init();

curl_setopt_array($curl, [
  CURLOPT_URL => "https://api.together.ai/v1/compute/clusters",
  CURLOPT_RETURNTRANSFER => true,
  CURLOPT_ENCODING => "",
  CURLOPT_MAXREDIRS => 10,
  CURLOPT_TIMEOUT => 30,
  CURLOPT_HTTP_VERSION => CURL_HTTP_VERSION_1_1,
  CURLOPT_CUSTOMREQUEST => "POST",
  CURLOPT_POSTFIELDS => json_encode([
    'region' => '<string>',
    'num_gpus' => 123,
    'cluster_name' => '<string>',
    'nvidia_version_id' => '<string>',
    'duration_days' => 123,
    'volume_id' => '<string>',
    'auto_scale_max_gpus' => 123,
    'slurm_shm_size_gib' => 123,
    'capacity_pool_id' => '<string>',
    'reservation_start_time' => '2023-11-07T05:31:56Z',
    'reservation_end_time' => '2023-11-07T05:31:56Z',
    'install_traefik' => false,
    'cuda_version' => '<string>',
    'nvidia_driver_version' => '<string>',
    'slurm_image' => '<string>',
    'project_id' => '<string>',
    'acceptance_tests_params' => [
        'enabled' => true,
        'gpu_burn_duration' => 123,
        'nccl_single_node_skipped' => true,
        'gpu_burn_skipped' => true,
        'dcgm_diag_skipped' => true,
        'nccl_multi_node_skipped' => true,
        'storage_skipped' => true
    ],
    'num_capacity_pool_gpus' => 123,
    'auto_scale' => true,
    'num_preemptible_gpus' => 123,
    'num_reserved_gpus' => 123,
    'add_ons' => [
        [
                'name' => '<string>',
                'add_on_type' => '<string>',
                'config' => [
                                'dashboard' => [
                                                                'enabled' => true
                                ],
                                'ingress' => [
                                                                'enabled' => true
                                ],
                                'slurm_web' => [
                                                                'enabled' => true
                                ],
                                'headlamp' => [
                                                                'enabled' => true
                                ]
                ]
        ]
    ]
  ]),
  CURLOPT_HTTPHEADER => [
    "Authorization: Bearer <token>",
    "Content-Type: application/json"
  ],
]);

$response = curl_exec($curl);
$err = curl_error($curl);

curl_close($curl);

if ($err) {
  echo "cURL Error #:" . $err;
} else {
  echo $response;
}

package main

import (
	"fmt"
	"strings"
	"net/http"
	"io"
)

func main() {

	url := "https://api.together.ai/v1/compute/clusters"

	payload := strings.NewReader("{\n  \"region\": \"<string>\",\n  \"num_gpus\": 123,\n  \"cluster_name\": \"<string>\",\n  \"nvidia_version_id\": \"<string>\",\n  \"duration_days\": 123,\n  \"volume_id\": \"<string>\",\n  \"auto_scale_max_gpus\": 123,\n  \"slurm_shm_size_gib\": 123,\n  \"capacity_pool_id\": \"<string>\",\n  \"reservation_start_time\": \"2023-11-07T05:31:56Z\",\n  \"reservation_end_time\": \"2023-11-07T05:31:56Z\",\n  \"install_traefik\": false,\n  \"cuda_version\": \"<string>\",\n  \"nvidia_driver_version\": \"<string>\",\n  \"slurm_image\": \"<string>\",\n  \"project_id\": \"<string>\",\n  \"acceptance_tests_params\": {\n    \"enabled\": true,\n    \"gpu_burn_duration\": 123,\n    \"nccl_single_node_skipped\": true,\n    \"gpu_burn_skipped\": true,\n    \"dcgm_diag_skipped\": true,\n    \"nccl_multi_node_skipped\": true,\n    \"storage_skipped\": true\n  },\n  \"num_capacity_pool_gpus\": 123,\n  \"auto_scale\": true,\n  \"num_preemptible_gpus\": 123,\n  \"num_reserved_gpus\": 123,\n  \"add_ons\": [\n    {\n      \"name\": \"<string>\",\n      \"add_on_type\": \"<string>\",\n      \"config\": {\n        \"dashboard\": {\n          \"enabled\": true\n        },\n        \"ingress\": {\n          \"enabled\": true\n        },\n        \"slurm_web\": {\n          \"enabled\": true\n        },\n        \"headlamp\": {\n          \"enabled\": true\n        }\n      }\n    }\n  ]\n}")

	req, _ := http.NewRequest("POST", url, payload)

	req.Header.Add("Authorization", "Bearer <token>")
	req.Header.Add("Content-Type", "application/json")

	res, _ := http.DefaultClient.Do(req)

	defer res.Body.Close()
	body, _ := io.ReadAll(res.Body)

	fmt.Println(string(body))

}

HttpResponse<String> response = Unirest.post("https://api.together.ai/v1/compute/clusters")
  .header("Authorization", "Bearer <token>")
  .header("Content-Type", "application/json")
  .body("{\n  \"region\": \"<string>\",\n  \"num_gpus\": 123,\n  \"cluster_name\": \"<string>\",\n  \"nvidia_version_id\": \"<string>\",\n  \"duration_days\": 123,\n  \"volume_id\": \"<string>\",\n  \"auto_scale_max_gpus\": 123,\n  \"slurm_shm_size_gib\": 123,\n  \"capacity_pool_id\": \"<string>\",\n  \"reservation_start_time\": \"2023-11-07T05:31:56Z\",\n  \"reservation_end_time\": \"2023-11-07T05:31:56Z\",\n  \"install_traefik\": false,\n  \"cuda_version\": \"<string>\",\n  \"nvidia_driver_version\": \"<string>\",\n  \"slurm_image\": \"<string>\",\n  \"project_id\": \"<string>\",\n  \"acceptance_tests_params\": {\n    \"enabled\": true,\n    \"gpu_burn_duration\": 123,\n    \"nccl_single_node_skipped\": true,\n    \"gpu_burn_skipped\": true,\n    \"dcgm_diag_skipped\": true,\n    \"nccl_multi_node_skipped\": true,\n    \"storage_skipped\": true\n  },\n  \"num_capacity_pool_gpus\": 123,\n  \"auto_scale\": true,\n  \"num_preemptible_gpus\": 123,\n  \"num_reserved_gpus\": 123,\n  \"add_ons\": [\n    {\n      \"name\": \"<string>\",\n      \"add_on_type\": \"<string>\",\n      \"config\": {\n        \"dashboard\": {\n          \"enabled\": true\n        },\n        \"ingress\": {\n          \"enabled\": true\n        },\n        \"slurm_web\": {\n          \"enabled\": true\n        },\n        \"headlamp\": {\n          \"enabled\": true\n        }\n      }\n    }\n  ]\n}")
  .asString();

require 'uri'
require 'net/http'

url = URI("https://api.together.ai/v1/compute/clusters")

http = Net::HTTP.new(url.host, url.port)
http.use_ssl = true

request = Net::HTTP::Post.new(url)
request["Authorization"] = 'Bearer <token>'
request["Content-Type"] = 'application/json'
request.body = "{\n  \"region\": \"<string>\",\n  \"num_gpus\": 123,\n  \"cluster_name\": \"<string>\",\n  \"nvidia_version_id\": \"<string>\",\n  \"duration_days\": 123,\n  \"volume_id\": \"<string>\",\n  \"auto_scale_max_gpus\": 123,\n  \"slurm_shm_size_gib\": 123,\n  \"capacity_pool_id\": \"<string>\",\n  \"reservation_start_time\": \"2023-11-07T05:31:56Z\",\n  \"reservation_end_time\": \"2023-11-07T05:31:56Z\",\n  \"install_traefik\": false,\n  \"cuda_version\": \"<string>\",\n  \"nvidia_driver_version\": \"<string>\",\n  \"slurm_image\": \"<string>\",\n  \"project_id\": \"<string>\",\n  \"acceptance_tests_params\": {\n    \"enabled\": true,\n    \"gpu_burn_duration\": 123,\n    \"nccl_single_node_skipped\": true,\n    \"gpu_burn_skipped\": true,\n    \"dcgm_diag_skipped\": true,\n    \"nccl_multi_node_skipped\": true,\n    \"storage_skipped\": true\n  },\n  \"num_capacity_pool_gpus\": 123,\n  \"auto_scale\": true,\n  \"num_preemptible_gpus\": 123,\n  \"num_reserved_gpus\": 123,\n  \"add_ons\": [\n    {\n      \"name\": \"<string>\",\n      \"add_on_type\": \"<string>\",\n      \"config\": {\n        \"dashboard\": {\n          \"enabled\": true\n        },\n        \"ingress\": {\n          \"enabled\": true\n        },\n        \"slurm_web\": {\n          \"enabled\": true\n        },\n        \"headlamp\": {\n          \"enabled\": true\n        }\n      }\n    }\n  ]\n}"

response = http.request(request)
puts response.read_body

{
  "cluster_id": "<string>",
  "cluster_type": "KUBERNETES",
  "region": "<string>",
  "gpu_type": "H100_SXM",
  "cluster_name": "<string>",
  "volumes": [
    {
      "volume_id": "<string>",
      "volume_name": "<string>",
      "size_tib": 123,
      "status": "<string>"
    }
  ],
  "status": "WaitingForControlPlaneNodes",
  "control_plane_nodes": [
    {
      "node_id": "<string>",
      "status": "<string>",
      "host_name": "<string>",
      "num_cpu_cores": 123,
      "memory_gib": 123,
      "network": "<string>",
      "phase_transitions": [
        {
          "phase": "NODE_PHASE_PENDING",
          "transition_time": "2023-11-07T05:31:56Z"
        }
      ],
      "public_ipv4": "<string>"
    }
  ],
  "gpu_worker_nodes": [
    {
      "node_id": "<string>",
      "status": "<string>",
      "host_name": "<string>",
      "num_cpu_cores": 123,
      "num_gpus": 123,
      "memory_gib": 123,
      "networks": [
        "<string>"
      ],
      "phase_transitions": [
        {
          "phase": "NODE_PHASE_PENDING",
          "transition_time": "2023-11-07T05:31:56Z"
        }
      ],
      "instance_id": "<string>",
      "latest_remediation": {
        "id": "<string>",
        "cluster_id": "<string>",
        "instance_id": "<string>",
        "mode": "REMEDIATION_MODE_VM_ONLY",
        "trigger": "REMEDIATION_TRIGGER_MANUAL",
        "state": "PENDING_APPROVAL",
        "reason": "<string>",
        "active_health_check_run_id": "<string>",
        "passive_health_check_event_id": "<string>",
        "requested_by": "<string>",
        "create_time": "2023-11-07T05:31:56Z",
        "reviewed_by": "<string>",
        "review_time": "2023-11-07T05:31:56Z",
        "review_comment": "<string>",
        "start_time": "2023-11-07T05:31:56Z",
        "end_time": "2023-11-07T05:31:56Z",
        "error_message": "<string>",
        "update_time": "2023-11-07T05:31:56Z",
        "instance_name": "<string>",
        "linked_alerts": [
          {
            "passive_health_check_alert_id": "<string>",
            "cluster_id": "<string>",
            "target_vm": "<string>",
            "alert_name": "<string>",
            "severity": "PHC_SEVERITY_INFO",
            "annotations": {},
            "started_at": "2023-11-07T05:31:56Z",
            "annotation": {
              "title": "<string>",
              "description": "<string>",
              "summary_line": "<string>",
              "xid": {
                "events": [
                  {
                    "xid_code": "<string>",
                    "mnemonic": "<string>",
                    "count": 123
                  }
                ]
              },
              "slurm_node_unavailable": {
                "reason": "<string>"
              }
            },
            "instance_id": "<string>",
            "resolved_at": "2023-11-07T05:31:56Z",
            "node_remediation_intent_id": "<string>"
          }
        ]
      },
      "slurm_worker_hostname": "<string>",
      "marked_for_deletion": true,
      "public_ipv4": "<string>",
      "ib_hca_type": "<string>",
      "ib_hca_count": 123,
      "nvswitch_count": 123,
      "nvswitch_type": "<string>",
      "ephemeral_storage": "<string>",
      "auto_remediation_enabled": true,
      "deleted_at": "2023-11-07T05:31:56Z"
    }
  ],
  "kube_config": "<string>",
  "num_gpus": 123,
  "cuda_version": "<string>",
  "nvidia_driver_version": "<string>",
  "project_id": "<string>",
  "num_cpu_workers": 123,
  "phase_transitions": [
    {
      "phase": "CLUSTER_PHASE_QUEUED",
      "transition_time": "2023-11-07T05:31:56Z"
    }
  ],
  "desired_preemptible_gpus": 123,
  "allocated_preemptible_gpus": 123,
  "billing_type": "RESERVED",
  "add_ons": [
    {
      "name": "<string>",
      "add_on_type": "<string>",
      "config": {
        "dashboard": {
          "enabled": true
        },
        "ingress": {
          "enabled": true
        },
        "slurm_web": {
          "enabled": true
        },
        "headlamp": {
          "enabled": true
        }
      },
      "state": {
        "dashboard": {},
        "ingress": {},
        "slurm_web": {},
        "headlamp": {}
      }
    }
  ],
  "num_capacity_pool_gpus": 123,
  "num_reserved_gpus": 123,
  "duration_hours": 123,
  "slurm_shm_size_gib": 123,
  "capacity_pool_id": "<string>",
  "reservation_start_time": "2023-11-07T05:31:56Z",
  "reservation_end_time": "2023-11-07T05:31:56Z",
  "install_traefik": true,
  "created_at": "2023-11-07T05:31:56Z",
  "oidc_config": {
    "issuer_url": "<string>",
    "client_id": "<string>",
    "username_claim": "<string>",
    "username_prefix": "<string>",
    "group_claim": "<string>",
    "group_prefix": "<string>",
    "ca_cert": "<string>"
  },
  "cluster_config": {
    "load_balancer": "NONE",
    "kubernetes_dashboard_enabled": true,
    "jumphost_enabled": true,
    "slurm_startup_scripts": {
      "worker_prolog": "<string>",
      "worker_epilog": "<string>",
      "controller_prolog": "<string>",
      "controller_epilog": "<string>",
      "login_init_script": "<string>",
      "nodeset_init_script": "<string>",
      "extra_slurm_conf": "<string>"
    },
    "ingress": {
      "enabled": true
    },
    "observability": {
      "enabled": true
    },
    "gpu_operator_version": "<string>",
    "network_operator_version": "<string>",
    "ssh_ca_enabled": true
  },
  "machine_cluster_id": "<string>",
  "first_ready_at": "2023-11-07T05:31:56Z",
  "is_in_substrate": true,
  "control_plane_ready": true,
  "ums_project_id": "<string>",
  "ums_org_id": "<string>",
  "os_image": "<string>",
  "nvidia_driver_version_id": "<string>",
  "deleted_gpu_worker_nodes": [
    {
      "node_id": "<string>",
      "status": "<string>",
      "host_name": "<string>",
      "num_cpu_cores": 123,
      "num_gpus": 123,
      "memory_gib": 123,
      "networks": [
        "<string>"
      ],
      "phase_transitions": [
        {
          "phase": "NODE_PHASE_PENDING",
          "transition_time": "2023-11-07T05:31:56Z"
        }
      ],
      "instance_id": "<string>",
      "latest_remediation": {
        "id": "<string>",
        "cluster_id": "<string>",
        "instance_id": "<string>",
        "mode": "REMEDIATION_MODE_VM_ONLY",
        "trigger": "REMEDIATION_TRIGGER_MANUAL",
        "state": "PENDING_APPROVAL",
        "reason": "<string>",
        "active_health_check_run_id": "<string>",
        "passive_health_check_event_id": "<string>",
        "requested_by": "<string>",
        "create_time": "2023-11-07T05:31:56Z",
        "reviewed_by": "<string>",
        "review_time": "2023-11-07T05:31:56Z",
        "review_comment": "<string>",
        "start_time": "2023-11-07T05:31:56Z",
        "end_time": "2023-11-07T05:31:56Z",
        "error_message": "<string>",
        "update_time": "2023-11-07T05:31:56Z",
        "instance_name": "<string>",
        "linked_alerts": [
          {
            "passive_health_check_alert_id": "<string>",
            "cluster_id": "<string>",
            "target_vm": "<string>",
            "alert_name": "<string>",
            "severity": "PHC_SEVERITY_INFO",
            "annotations": {},
            "started_at": "2023-11-07T05:31:56Z",
            "annotation": {
              "title": "<string>",
              "description": "<string>",
              "summary_line": "<string>",
              "xid": {
                "events": [
                  {
                    "xid_code": "<string>",
                    "mnemonic": "<string>",
                    "count": 123
                  }
                ]
              },
              "slurm_node_unavailable": {
                "reason": "<string>"
              }
            },
            "instance_id": "<string>",
            "resolved_at": "2023-11-07T05:31:56Z",
            "node_remediation_intent_id": "<string>"
          }
        ]
      },
      "slurm_worker_hostname": "<string>",
      "marked_for_deletion": true,
      "public_ipv4": "<string>",
      "ib_hca_type": "<string>",
      "ib_hca_count": 123,
      "nvswitch_count": 123,
      "nvswitch_type": "<string>",
      "ephemeral_storage": "<string>",
      "auto_remediation_enabled": true,
      "deleted_at": "2023-11-07T05:31:56Z"
    }
  ],
  "node_lifecycle_events": [
    {
      "node_id": "<string>",
      "reason": "<string>",
      "message": "<string>",
      "timestamp": "2023-11-07T05:31:56Z"
    }
  ]
}

Authorizations

Authorization

string

header

default:default

required

Bearer authentication header of the form Bearer <token>, where <token> is your auth token.

Body

application/json

Option 1
Option 2

GPU Cluster create request

region

string

required

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

gpu_type

enum<string>

required

Type of GPU to use in the cluster

Available options:

H100_SXM,

H200_SXM,

RTX_6000_PCI,

L40_PCIE,

B200_SXM,

H100_SXM_INF,

B300_SXM,

GB200_NVL

num_gpus

integer

required

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

cluster_name

string

required

Name of the GPU cluster.

billing_type

enum<string>

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.

Available options:

RESERVED,

ON_DEMAND,

SCHEDULED_CAPACITY

nvidia_version_id

string

required

Canonical region-specific NVIDIA version ID. If cuda_version and nvidia_driver_version are also set, they must resolve to the same catalog entry.

cluster_type

enum<string>

Type of cluster to create.

Available options:

KUBERNETES,

SLURM

duration_days

integer

Duration in days to keep the cluster running.

shared_volume

object

Inline configuration to create a shared volume with the cluster creation.

Show child attributes

volume_id

string

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

auto_scale_max_gpus

integer

Maximum number of GPUs to which the cluster can be auto-scaled up.

slurm_shm_size_gib

integer

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

capacity_pool_id

string

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_time

string<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_time

string<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_traefik

boolean

default:false

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

cuda_version

string

Legacy CUDA selector for this cluster. Bare semantic values such as 12.5 select ubuntu-22.04; existing OS-suffixed values remain accepted for compatibility. Must be paired with nvidia_driver_version. Prefer nvidia_version_id for new integrations.

nvidia_driver_version

string

Legacy NVIDIA driver selector for this cluster. For example, 550. Must be paired with cuda_version. Prefer nvidia_version_id for new integrations.

slurm_image

string

Custom Slurm image for Slurm clusters.

oidc_config

object

Show child attributes

project_id

string

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

acceptance_tests_params

object

AcceptanceTestsParams groups all GPU acceptance test options when enabled is true.

Show child attributes

cluster_config

object

Show child attributes

num_capacity_pool_gpus

integer

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

auto_scale

boolean

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_gpus

integer

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_gpus

integer

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

add_ons

object[]

Add-ons to enable on the cluster at creation time.

Show child attributes

Response

200 - application/json

cluster_id

string

required

cluster_type

enum<string>

required

Type of cluster.

Available options:

KUBERNETES,

SLURM

region

string

required

gpu_type

enum<string>

required

Type of GPU used by the cluster.

Available options:

H100_SXM,

H200_SXM,

RTX_6000_PCI,

L40_PCIE,

B200_SXM,

H100_SXM_INF,

B300_SXM,

GB200_NVL

cluster_name

string

required

volumes

object[]

required

Show child attributes

status

enum<string>

required

Current status of the GPU cluster.

Available options:

WaitingForControlPlaneNodes,

WaitingForDataPlaneNodes,

WaitingForSubnet,

WaitingForSharedVolume,

InstallingDrivers,

RunningAcceptanceTests,

Paused,

OnDemandComputePaused,

Ready,

Degraded,

Deleting

control_plane_nodes

object[]

required

Show child attributes

gpu_worker_nodes

object[]

required

Show child attributes

kube_config

string

required

num_gpus

integer

required

cuda_version

string

required

nvidia_driver_version

string

required

project_id

string

required

num_cpu_workers

integer

required

Number of CPU-only worker nodes in the cluster.

phase_transitions

object[]

required

Cluster-level phase transition history.

Show child attributes

desired_preemptible_gpus

integer

required

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

allocated_preemptible_gpus

integer

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

enum<string>

required

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

Available options:

RESERVED,

ON_DEMAND,

SCHEDULED_CAPACITY

add_ons

object[]

required

Enabled add-ons on this cluster. Only add-ons with enabled=true in their config are returned.

Show child attributes

num_capacity_pool_gpus

integer<int32>

required

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

num_reserved_gpus

integer<int32>

required

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

duration_hours

integer

slurm_shm_size_gib

integer

capacity_pool_id

string

reservation_start_time

string<date-time>

reservation_end_time

string<date-time>

install_traefik

boolean

created_at

string<date-time>

oidc_config

object

Show child attributes

cluster_config

object

Show child attributes

machine_cluster_id

string

ID of the machine cluster backing this GPU cluster.

first_ready_at

string<date-time>

Timestamp when the cluster first reached the Ready phase.

is_in_substrate

boolean

Whether the cluster runs on the Together-managed GPU cluster platform.

control_plane_ready

boolean

Whether the control plane is currently ready.

ums_project_id

string

UMS project ID associated with this cluster.

ums_org_id

string

UMS organization ID associated with this cluster.

os_image

string

Data-volume image name for GPU worker nodes.

nvidia_driver_version_id

string

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

deleted_gpu_worker_nodes

object[]

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.

Show child attributes

node_lifecycle_events

object[]

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.

Show child attributes

⌘I

Together AI SDK (Python)

from together import Together

client = Together()

response = client.clusters.create(
  cluster_name="my-gpu-cluster",
  region="us-central-8",
  gpu_type="H100_SXM",
  num_gpus=8,
  nvidia_driver_version="560",
  cuda_version="12.6",
  billing_type="ON_DEMAND",
)

print(response.cluster_id)

import Together from "together-ai";

const client = new Together();

const response = await client.clusters.create({
  cluster_name: "my-gpu-cluster",
  region: "us-central-8",
  gpu_type: "H100_SXM",
  num_gpus: 8,
  nvidia_driver_version: "560",
  cuda_version: "12.6",
  billing_type: "ON_DEMAND",
});

console.log(response.cluster_id)

import Together from "together-ai";

const client = new Together();

const response = await client.clusters.create({
  cluster_name: "my-gpu-cluster",
  region: "us-central-8",
  gpu_type: "H100_SXM",
  num_gpus: 8,
  nvidia_driver_version: "560",
  cuda_version: "12.6",
  billing_type: "ON_DEMAND",
});

console.log(response.cluster_id)

tg clusters create \
  --name my-gpu-cluster \
  --region us-central-8 \
  --gpu-type H100_SXM \
  --cluster-type KUBERNETES \
  --num-gpus 8 \
  --billing-type ON_DEMAND \
  --nvidia-driver-version 560 \
  --cuda-version 12.6

<?php

$curl = curl_init();

curl_setopt_array($curl, [
  CURLOPT_URL => "https://api.together.ai/v1/compute/clusters",
  CURLOPT_RETURNTRANSFER => true,
  CURLOPT_ENCODING => "",
  CURLOPT_MAXREDIRS => 10,
  CURLOPT_TIMEOUT => 30,
  CURLOPT_HTTP_VERSION => CURL_HTTP_VERSION_1_1,
  CURLOPT_CUSTOMREQUEST => "POST",
  CURLOPT_POSTFIELDS => json_encode([
    'region' => '<string>',
    'num_gpus' => 123,
    'cluster_name' => '<string>',
    'nvidia_version_id' => '<string>',
    'duration_days' => 123,
    'volume_id' => '<string>',
    'auto_scale_max_gpus' => 123,
    'slurm_shm_size_gib' => 123,
    'capacity_pool_id' => '<string>',
    'reservation_start_time' => '2023-11-07T05:31:56Z',
    'reservation_end_time' => '2023-11-07T05:31:56Z',
    'install_traefik' => false,
    'cuda_version' => '<string>',
    'nvidia_driver_version' => '<string>',
    'slurm_image' => '<string>',
    'project_id' => '<string>',
    'acceptance_tests_params' => [
        'enabled' => true,
        'gpu_burn_duration' => 123,
        'nccl_single_node_skipped' => true,
        'gpu_burn_skipped' => true,
        'dcgm_diag_skipped' => true,
        'nccl_multi_node_skipped' => true,
        'storage_skipped' => true
    ],
    'num_capacity_pool_gpus' => 123,
    'auto_scale' => true,
    'num_preemptible_gpus' => 123,
    'num_reserved_gpus' => 123,
    'add_ons' => [
        [
                'name' => '<string>',
                'add_on_type' => '<string>',
                'config' => [
                                'dashboard' => [
                                                                'enabled' => true
                                ],
                                'ingress' => [
                                                                'enabled' => true
                                ],
                                'slurm_web' => [
                                                                'enabled' => true
                                ],
                                'headlamp' => [
                                                                'enabled' => true
                                ]
                ]
        ]
    ]
  ]),
  CURLOPT_HTTPHEADER => [
    "Authorization: Bearer <token>",
    "Content-Type: application/json"
  ],
]);

$response = curl_exec($curl);
$err = curl_error($curl);

curl_close($curl);

if ($err) {
  echo "cURL Error #:" . $err;
} else {
  echo $response;
}

package main

import (
	"fmt"
	"strings"
	"net/http"
	"io"
)

func main() {

	url := "https://api.together.ai/v1/compute/clusters"

	payload := strings.NewReader("{\n  \"region\": \"<string>\",\n  \"num_gpus\": 123,\n  \"cluster_name\": \"<string>\",\n  \"nvidia_version_id\": \"<string>\",\n  \"duration_days\": 123,\n  \"volume_id\": \"<string>\",\n  \"auto_scale_max_gpus\": 123,\n  \"slurm_shm_size_gib\": 123,\n  \"capacity_pool_id\": \"<string>\",\n  \"reservation_start_time\": \"2023-11-07T05:31:56Z\",\n  \"reservation_end_time\": \"2023-11-07T05:31:56Z\",\n  \"install_traefik\": false,\n  \"cuda_version\": \"<string>\",\n  \"nvidia_driver_version\": \"<string>\",\n  \"slurm_image\": \"<string>\",\n  \"project_id\": \"<string>\",\n  \"acceptance_tests_params\": {\n    \"enabled\": true,\n    \"gpu_burn_duration\": 123,\n    \"nccl_single_node_skipped\": true,\n    \"gpu_burn_skipped\": true,\n    \"dcgm_diag_skipped\": true,\n    \"nccl_multi_node_skipped\": true,\n    \"storage_skipped\": true\n  },\n  \"num_capacity_pool_gpus\": 123,\n  \"auto_scale\": true,\n  \"num_preemptible_gpus\": 123,\n  \"num_reserved_gpus\": 123,\n  \"add_ons\": [\n    {\n      \"name\": \"<string>\",\n      \"add_on_type\": \"<string>\",\n      \"config\": {\n        \"dashboard\": {\n          \"enabled\": true\n        },\n        \"ingress\": {\n          \"enabled\": true\n        },\n        \"slurm_web\": {\n          \"enabled\": true\n        },\n        \"headlamp\": {\n          \"enabled\": true\n        }\n      }\n    }\n  ]\n}")

	req, _ := http.NewRequest("POST", url, payload)

	req.Header.Add("Authorization", "Bearer <token>")
	req.Header.Add("Content-Type", "application/json")

	res, _ := http.DefaultClient.Do(req)

	defer res.Body.Close()
	body, _ := io.ReadAll(res.Body)

	fmt.Println(string(body))

}

HttpResponse<String> response = Unirest.post("https://api.together.ai/v1/compute/clusters")
  .header("Authorization", "Bearer <token>")
  .header("Content-Type", "application/json")
  .body("{\n  \"region\": \"<string>\",\n  \"num_gpus\": 123,\n  \"cluster_name\": \"<string>\",\n  \"nvidia_version_id\": \"<string>\",\n  \"duration_days\": 123,\n  \"volume_id\": \"<string>\",\n  \"auto_scale_max_gpus\": 123,\n  \"slurm_shm_size_gib\": 123,\n  \"capacity_pool_id\": \"<string>\",\n  \"reservation_start_time\": \"2023-11-07T05:31:56Z\",\n  \"reservation_end_time\": \"2023-11-07T05:31:56Z\",\n  \"install_traefik\": false,\n  \"cuda_version\": \"<string>\",\n  \"nvidia_driver_version\": \"<string>\",\n  \"slurm_image\": \"<string>\",\n  \"project_id\": \"<string>\",\n  \"acceptance_tests_params\": {\n    \"enabled\": true,\n    \"gpu_burn_duration\": 123,\n    \"nccl_single_node_skipped\": true,\n    \"gpu_burn_skipped\": true,\n    \"dcgm_diag_skipped\": true,\n    \"nccl_multi_node_skipped\": true,\n    \"storage_skipped\": true\n  },\n  \"num_capacity_pool_gpus\": 123,\n  \"auto_scale\": true,\n  \"num_preemptible_gpus\": 123,\n  \"num_reserved_gpus\": 123,\n  \"add_ons\": [\n    {\n      \"name\": \"<string>\",\n      \"add_on_type\": \"<string>\",\n      \"config\": {\n        \"dashboard\": {\n          \"enabled\": true\n        },\n        \"ingress\": {\n          \"enabled\": true\n        },\n        \"slurm_web\": {\n          \"enabled\": true\n        },\n        \"headlamp\": {\n          \"enabled\": true\n        }\n      }\n    }\n  ]\n}")
  .asString();

require 'uri'
require 'net/http'

url = URI("https://api.together.ai/v1/compute/clusters")

http = Net::HTTP.new(url.host, url.port)
http.use_ssl = true

request = Net::HTTP::Post.new(url)
request["Authorization"] = 'Bearer <token>'
request["Content-Type"] = 'application/json'
request.body = "{\n  \"region\": \"<string>\",\n  \"num_gpus\": 123,\n  \"cluster_name\": \"<string>\",\n  \"nvidia_version_id\": \"<string>\",\n  \"duration_days\": 123,\n  \"volume_id\": \"<string>\",\n  \"auto_scale_max_gpus\": 123,\n  \"slurm_shm_size_gib\": 123,\n  \"capacity_pool_id\": \"<string>\",\n  \"reservation_start_time\": \"2023-11-07T05:31:56Z\",\n  \"reservation_end_time\": \"2023-11-07T05:31:56Z\",\n  \"install_traefik\": false,\n  \"cuda_version\": \"<string>\",\n  \"nvidia_driver_version\": \"<string>\",\n  \"slurm_image\": \"<string>\",\n  \"project_id\": \"<string>\",\n  \"acceptance_tests_params\": {\n    \"enabled\": true,\n    \"gpu_burn_duration\": 123,\n    \"nccl_single_node_skipped\": true,\n    \"gpu_burn_skipped\": true,\n    \"dcgm_diag_skipped\": true,\n    \"nccl_multi_node_skipped\": true,\n    \"storage_skipped\": true\n  },\n  \"num_capacity_pool_gpus\": 123,\n  \"auto_scale\": true,\n  \"num_preemptible_gpus\": 123,\n  \"num_reserved_gpus\": 123,\n  \"add_ons\": [\n    {\n      \"name\": \"<string>\",\n      \"add_on_type\": \"<string>\",\n      \"config\": {\n        \"dashboard\": {\n          \"enabled\": true\n        },\n        \"ingress\": {\n          \"enabled\": true\n        },\n        \"slurm_web\": {\n          \"enabled\": true\n        },\n        \"headlamp\": {\n          \"enabled\": true\n        }\n      }\n    }\n  ]\n}"

response = http.request(request)
puts response.read_body

{
  "cluster_id": "<string>",
  "cluster_type": "KUBERNETES",
  "region": "<string>",
  "gpu_type": "H100_SXM",
  "cluster_name": "<string>",
  "volumes": [
    {
      "volume_id": "<string>",
      "volume_name": "<string>",
      "size_tib": 123,
      "status": "<string>"
    }
  ],
  "status": "WaitingForControlPlaneNodes",
  "control_plane_nodes": [
    {
      "node_id": "<string>",
      "status": "<string>",
      "host_name": "<string>",
      "num_cpu_cores": 123,
      "memory_gib": 123,
      "network": "<string>",
      "phase_transitions": [
        {
          "phase": "NODE_PHASE_PENDING",
          "transition_time": "2023-11-07T05:31:56Z"
        }
      ],
      "public_ipv4": "<string>"
    }
  ],
  "gpu_worker_nodes": [
    {
      "node_id": "<string>",
      "status": "<string>",
      "host_name": "<string>",
      "num_cpu_cores": 123,
      "num_gpus": 123,
      "memory_gib": 123,
      "networks": [
        "<string>"
      ],
      "phase_transitions": [
        {
          "phase": "NODE_PHASE_PENDING",
          "transition_time": "2023-11-07T05:31:56Z"
        }
      ],
      "instance_id": "<string>",
      "latest_remediation": {
        "id": "<string>",
        "cluster_id": "<string>",
        "instance_id": "<string>",
        "mode": "REMEDIATION_MODE_VM_ONLY",
        "trigger": "REMEDIATION_TRIGGER_MANUAL",
        "state": "PENDING_APPROVAL",
        "reason": "<string>",
        "active_health_check_run_id": "<string>",
        "passive_health_check_event_id": "<string>",
        "requested_by": "<string>",
        "create_time": "2023-11-07T05:31:56Z",
        "reviewed_by": "<string>",
        "review_time": "2023-11-07T05:31:56Z",
        "review_comment": "<string>",
        "start_time": "2023-11-07T05:31:56Z",
        "end_time": "2023-11-07T05:31:56Z",
        "error_message": "<string>",
        "update_time": "2023-11-07T05:31:56Z",
        "instance_name": "<string>",
        "linked_alerts": [
          {
            "passive_health_check_alert_id": "<string>",
            "cluster_id": "<string>",
            "target_vm": "<string>",
            "alert_name": "<string>",
            "severity": "PHC_SEVERITY_INFO",
            "annotations": {},
            "started_at": "2023-11-07T05:31:56Z",
            "annotation": {
              "title": "<string>",
              "description": "<string>",
              "summary_line": "<string>",
              "xid": {
                "events": [
                  {
                    "xid_code": "<string>",
                    "mnemonic": "<string>",
                    "count": 123
                  }
                ]
              },
              "slurm_node_unavailable": {
                "reason": "<string>"
              }
            },
            "instance_id": "<string>",
            "resolved_at": "2023-11-07T05:31:56Z",
            "node_remediation_intent_id": "<string>"
          }
        ]
      },
      "slurm_worker_hostname": "<string>",
      "marked_for_deletion": true,
      "public_ipv4": "<string>",
      "ib_hca_type": "<string>",
      "ib_hca_count": 123,
      "nvswitch_count": 123,
      "nvswitch_type": "<string>",
      "ephemeral_storage": "<string>",
      "auto_remediation_enabled": true,
      "deleted_at": "2023-11-07T05:31:56Z"
    }
  ],
  "kube_config": "<string>",
  "num_gpus": 123,
  "cuda_version": "<string>",
  "nvidia_driver_version": "<string>",
  "project_id": "<string>",
  "num_cpu_workers": 123,
  "phase_transitions": [
    {
      "phase": "CLUSTER_PHASE_QUEUED",
      "transition_time": "2023-11-07T05:31:56Z"
    }
  ],
  "desired_preemptible_gpus": 123,
  "allocated_preemptible_gpus": 123,
  "billing_type": "RESERVED",
  "add_ons": [
    {
      "name": "<string>",
      "add_on_type": "<string>",
      "config": {
        "dashboard": {
          "enabled": true
        },
        "ingress": {
          "enabled": true
        },
        "slurm_web": {
          "enabled": true
        },
        "headlamp": {
          "enabled": true
        }
      },
      "state": {
        "dashboard": {},
        "ingress": {},
        "slurm_web": {},
        "headlamp": {}
      }
    }
  ],
  "num_capacity_pool_gpus": 123,
  "num_reserved_gpus": 123,
  "duration_hours": 123,
  "slurm_shm_size_gib": 123,
  "capacity_pool_id": "<string>",
  "reservation_start_time": "2023-11-07T05:31:56Z",
  "reservation_end_time": "2023-11-07T05:31:56Z",
  "install_traefik": true,
  "created_at": "2023-11-07T05:31:56Z",
  "oidc_config": {
    "issuer_url": "<string>",
    "client_id": "<string>",
    "username_claim": "<string>",
    "username_prefix": "<string>",
    "group_claim": "<string>",
    "group_prefix": "<string>",
    "ca_cert": "<string>"
  },
  "cluster_config": {
    "load_balancer": "NONE",
    "kubernetes_dashboard_enabled": true,
    "jumphost_enabled": true,
    "slurm_startup_scripts": {
      "worker_prolog": "<string>",
      "worker_epilog": "<string>",
      "controller_prolog": "<string>",
      "controller_epilog": "<string>",
      "login_init_script": "<string>",
      "nodeset_init_script": "<string>",
      "extra_slurm_conf": "<string>"
    },
    "ingress": {
      "enabled": true
    },
    "observability": {
      "enabled": true
    },
    "gpu_operator_version": "<string>",
    "network_operator_version": "<string>",
    "ssh_ca_enabled": true
  },
  "machine_cluster_id": "<string>",
  "first_ready_at": "2023-11-07T05:31:56Z",
  "is_in_substrate": true,
  "control_plane_ready": true,
  "ums_project_id": "<string>",
  "ums_org_id": "<string>",
  "os_image": "<string>",
  "nvidia_driver_version_id": "<string>",
  "deleted_gpu_worker_nodes": [
    {
      "node_id": "<string>",
      "status": "<string>",
      "host_name": "<string>",
      "num_cpu_cores": 123,
      "num_gpus": 123,
      "memory_gib": 123,
      "networks": [
        "<string>"
      ],
      "phase_transitions": [
        {
          "phase": "NODE_PHASE_PENDING",
          "transition_time": "2023-11-07T05:31:56Z"
        }
      ],
      "instance_id": "<string>",
      "latest_remediation": {
        "id": "<string>",
        "cluster_id": "<string>",
        "instance_id": "<string>",
        "mode": "REMEDIATION_MODE_VM_ONLY",
        "trigger": "REMEDIATION_TRIGGER_MANUAL",
        "state": "PENDING_APPROVAL",
        "reason": "<string>",
        "active_health_check_run_id": "<string>",
        "passive_health_check_event_id": "<string>",
        "requested_by": "<string>",
        "create_time": "2023-11-07T05:31:56Z",
        "reviewed_by": "<string>",
        "review_time": "2023-11-07T05:31:56Z",
        "review_comment": "<string>",
        "start_time": "2023-11-07T05:31:56Z",
        "end_time": "2023-11-07T05:31:56Z",
        "error_message": "<string>",
        "update_time": "2023-11-07T05:31:56Z",
        "instance_name": "<string>",
        "linked_alerts": [
          {
            "passive_health_check_alert_id": "<string>",
            "cluster_id": "<string>",
            "target_vm": "<string>",
            "alert_name": "<string>",
            "severity": "PHC_SEVERITY_INFO",
            "annotations": {},
            "started_at": "2023-11-07T05:31:56Z",
            "annotation": {
              "title": "<string>",
              "description": "<string>",
              "summary_line": "<string>",
              "xid": {
                "events": [
                  {
                    "xid_code": "<string>",
                    "mnemonic": "<string>",
                    "count": 123
                  }
                ]
              },
              "slurm_node_unavailable": {
                "reason": "<string>"
              }
            },
            "instance_id": "<string>",
            "resolved_at": "2023-11-07T05:31:56Z",
            "node_remediation_intent_id": "<string>"
          }
        ]
      },
      "slurm_worker_hostname": "<string>",
      "marked_for_deletion": true,
      "public_ipv4": "<string>",
      "ib_hca_type": "<string>",
      "ib_hca_count": 123,
      "nvswitch_count": 123,
      "nvswitch_type": "<string>",
      "ephemeral_storage": "<string>",
      "auto_remediation_enabled": true,
      "deleted_at": "2023-11-07T05:31:56Z"
    }
  ],
  "node_lifecycle_events": [
    {
      "node_id": "<string>",
      "reason": "<string>",
      "message": "<string>",
      "timestamp": "2023-11-07T05:31:56Z"
    }
  ]
}

TOGETHER APIS

SDK LIBRARIES

ERROR CODES

Authorizations

Body

Response