---
title: "Create an InfiniBand cluster of whole h100-8 machines (preview)"
method: POST
path: "/preview/clusters"
tags: ["clusters"]
---

# Create an InfiniBand cluster of whole h100-8 machines (preview)

`POST /preview/clusters`

## Request

- Base URL: `https://autoresearch.sfcompute.com`
- URL: `https://autoresearch.sfcompute.com/preview/clusters`
- Auth: HTTP bearer

Create an InfiniBand cluster. A cluster is 2 to 8 whole 8-GPU machines on a private InfiniBand network that we make for this cluster alone. Give chip "h100-8", nodes, and gpus. gpus must equal nodes x 8, and a mismatch never rounds. Each node is an ordinary h100-8 node named <name>-<rank>, and each node bills as an h100-8 node from the moment it is ready. The call never blocks. It returns the cluster in state "queued" with the rate. rate.cluster_per_min is the cost of all the nodes per minute. Preparation takes 10 to 45 minutes, and no node bills while the cluster is queued or preparing. Poll get_cluster until state is "running". Every node gets GMN_CLUSTER, GMN_CLUSTER_RANK, GMN_CLUSTER_SIZE and GMN_CLUSTER_MASTER_ADDR for torchrun. A cluster is all its nodes or none. If one node stops or is lost, the whole cluster ends and every disk is deleted. You cannot stop, delete or snapshot one node of a cluster. A call with the name of a live cluster and the same shape returns that cluster. network, clock_lock, profiling, scratch_gib and from_snapshot are not available for clusters. Clusters are a preview.

## Query parameters

- `workspace` string

## Request body

- object
  - `chip` string, required: The node type of every node. Only "h100-8" (also spelled "8xh100") is accepted, because a cluster uses whole machines.
  - `gpus` integer, required: The total number of GPUs. It must equal nodes x 8. This value is your statement of what you pay for, and a mismatch never rounds.
  - `home` string, nullable: The home path of your own image, as on create_node.
  - `image` string, nullable: The image of every node, as on create_node: a catalog name, or your own registry ref.
  - `max_wait` string, nullable: How long the cluster may wait for free machines, as a duration ("2h"). It applies only while the cluster state is "queued".
  - `mission` string, nullable, required: The mission the nodes belong to (open_mission first).
  - `name` string, required: The cluster name (lowercase letters, digits, '-'). It must be free among the live clusters of the workspace. The nodes are named <name>-0 to <name>-<nodes - 1>, and those node names must also be free. The cluster's private network gets this name too.
  - `nodes` integer, required: The number of nodes (whole machines), from 2 to the account maximum (8 by default; list_limits shows max_cluster_nodes).

## Response `200`

The capability's JSON result.

- Result: The capability's result: the same object the MCP tool returns as structuredContent. Resources carry an `object` type discriminator and an immutable id; money is integer micro-dollars in `*_usd_micros` fields.
  - `object` string: The resource type, when the result is one resource.

## Other responses

- `400`: Malformed request: bad JSON, a parameter that does not parse, or a value outside its range. Code `invalid`.
- `401`: No bearer token, or one this API cannot verify. Code `unauthenticated`.
- `403`: Authenticated, but the token's scopes or the account's role do not reach this operation. The message names the scope word to request. Code `forbidden`.
- `404`: No such route. Code `not_found`; the body names the OpenAPI document.
- `422`: A well-formed request the platform declined: no such node, a cap reached, a state that forbids the move. The message says which, and what to do instead. Code `refused`.
- `429`: Over this door's per-customer budget. Wait `Retry-After` seconds. Code `rate_limited`.
- `500`: Our fault. Retry; if it persists, quote the request-id. Code `internal`.

---

[API](https://skmtc.dev/givemeanode/apis/autoresearch-customer-api.md) · [All operations](https://skmtc.dev/givemeanode/apis/autoresearch-customer-api/llms.txt) · [OpenAPI document](https://skmtc.dev/givemeanode/apis/autoresearch-customer-api/revisions/f88dcb70ac6c?raw)