> ## Documentation Index > Fetch the complete documentation index at: https://runcrate.ai/docs/llms.txt > Use this file to discover all available pages before exploring further. # Get cluster > The cluster with its machines, how to connect (head SSH, hostfile, torchrun, mpirun and DeepSpeed commands, and per stack sbatch, kubectl or ray tunnels), `/shared`, the last 50 events, the last NCCL test and when billing started. Addresses and SSH commands appear once the cluster is up. ## OpenAPI ````yaml /api-reference/openapi.json get /clusters/{id} openapi: 3.1.0 info: title: Runcrate API version: 1.0.0 summary: OpenAI-compatible inference API + GPU infrastructure API. description: >- Runcrate exposes two API surfaces. The inference API at `https://api.runcrate.ai/v1` is OpenAI-compatible: it accepts the standard OpenAI SDK with the base URL changed. The infrastructure API at `https://www.runcrate.ai/api/v1` manages GPU instances, jobs, persistent volumes, environments, SSH keys, templates, and billing. Both share a single `rc_live_*` API key. Pricing is per-token, per-image, per-second, or per-minute on the inference API (varies by model; see https://www.runcrate.ai/api/models/catalog for live rates) and per-second on GPU rentals (see https://www.runcrate.ai/pricing for hourly rates per GPU class). All infrastructure API responses are wrapped in `{ "data": ... }`. List responses also include a `meta` object with pagination cursors. Error responses use `{ "error": { "code": "...", "message": "..." } }`. termsOfService: https://www.runcrate.ai/terms contact: name: Runcrate url: https://www.runcrate.ai/contact license: name: Proprietary url: https://www.runcrate.ai/terms servers: - url: https://api.runcrate.ai/v1 description: Inference API (OpenAI-compatible) - url: https://www.runcrate.ai/api/v1 description: >- Infrastructure API (instances, jobs, storage, environments, ssh-keys, templates, billing) security: - ApiKeyAuth: [] tags: - name: Chat description: OpenAI-compatible chat completions. - name: Messages description: Anthropic-compatible Messages API, for Claude Code and the Anthropic SDKs. - name: Responses description: >- OpenAI-compatible Responses API, for Codex and responses.create. Nothing is stored. - name: Images description: Text-to-image generation. - name: Videos description: Async text-to-video and image-to-video generation. - name: Audio description: Text-to-speech and speech-to-text. - name: Embeddings description: Vector embeddings for RAG and search. - name: Models description: Model catalog discovery. - name: Instances description: GPU instance lifecycle. - name: Jobs description: >- Run one command on its own GPU machine. The machine stops, and billing ends, when the command exits. - name: Schedules description: >- Start an instance or a job later: once at a set time, or on a repeating cron schedule in your timezone. - name: Clusters description: >- Multi-machine GPU clusters on a private network, with Slurm, Kubernetes or Ray, bought by the machine. All or nothing: every machine starts or none does, billed from when every machine is up. - name: Storage description: Persistent volume management. - name: Environments description: Resource isolation containers within a workspace. - name: Secrets description: >- Names of the secrets an environment's machines get. Values are set in the dashboard and never returned. - name: SSH Keys description: SSH key management for instance access. - name: Templates description: Pre-built instance images and configurations. - name: Billing description: Credit balance, transactions, usage metrics. - name: Model calls description: >- The log of calls to the inference API, kept 30 days: outcome, timing, tokens, cost, end user, session and tags. Never the prompt or the answer. paths: /clusters/{id}: servers: - url: https://www.runcrate.ai/api/v1 get: tags: - Clusters summary: Get cluster description: >- The cluster with its machines, how to connect (head SSH, hostfile, torchrun, mpirun and DeepSpeed commands, and per stack sbatch, kubectl or ray tunnels), `/shared`, the last 50 events, the last NCCL test and when billing started. Addresses and SSH commands appear once the cluster is up. operationId: getCluster parameters: - name: id in: path required: true schema: type: string format: uuid description: Cluster ID responses: '200': description: Cluster. content: application/json: schema: type: object required: - data properties: data: $ref: '#/components/schemas/ClusterDetail' '401': $ref: '#/components/responses/Unauthorized' '404': description: >- `not_found`: no such cluster in the environment, or `FEATURE_OFF`: self-serve clusters are not on for this workspace yet (request a quote in the dashboard). content: application/json: schema: $ref: '#/components/schemas/Error' components: schemas: ClusterDetail: allOf: - $ref: '#/components/schemas/Cluster' - type: object required: - nodes - connection - shared - events - last_test - billing - resize properties: nodes: type: array items: $ref: '#/components/schemas/ClusterNode' connection: type: object required: - head_ssh - hostfile - env - snippets properties: head_ssh: type: string nullable: true description: '`null` until the cluster is up.' hostfile: type: string description: >- One `node- slots=` line per node; also at `/shared/hostfile` (`/etc/runcrate/hostfile` when there is no shared folder). env: type: object properties: MASTER_ADDR: type: string MASTER_PORT: type: string NCCL_SOCKET_IFNAME: type: string snippets: type: object required: - torchrun - mpirun - deepspeed properties: torchrun: type: string mpirun: type: string deepspeed: type: string sbatch: type: string description: Slurm only. kubectl_tunnel: type: string description: Kubernetes only, once the cluster is up. ray_tunnel: type: string description: Ray only, once the cluster is up. shared: type: object required: - path - available properties: path: type: string enum: - /shared available: type: boolean description: False on container machines, which share no folder. detail: type: string volume: type: object properties: id: type: string name: type: string path: type: string enum: - /shared/volume events: type: array description: The last 50, newest first. items: type: object properties: id: type: integer at: type: string format: date-time kind: type: string rank: type: integer nullable: true message: type: string last_test: allOf: - $ref: '#/components/schemas/ClusterTest' nullable: true billing: type: object required: - billed_since - nodes_billed properties: billed_since: type: string format: date-time nullable: true description: When every machine was up; null before. nodes_billed: type: integer description: Machines billed now. resize: type: boolean description: >- Workers can be added (`POST /clusters/{id}/nodes`) and removed (`DELETE /clusters/{id}/nodes/{rank}`). Error: type: object required: - error properties: error: type: object required: - code - message properties: code: type: string description: >- Machine-readable error code (e.g. `validation_error`, `unauthorized`, `not_found`, `insufficient_credits`, `rate_limited`, `internal_error`). message: type: string description: Human-readable error message. details: type: object additionalProperties: true description: Optional structured error context. Cluster: type: object required: - id - name - status - stack - stack_status - stack_detail - node_count - gpu_type - gpus_per_node - deployment_type - host_tier - location - interconnect - hourly_rate_per_node - hourly_rate - created_at - up_at - ready_at - terminated_at properties: id: type: string format: uuid name: type: string status: type: string enum: - provisioning - installing - ready - degraded - terminating - terminated - failed description: >- `provisioning` until every machine is up and joined, then `installing` while the stack installs, then `ready`. `degraded`: the stack failed to install; the machines stay up. `failed`: it could not start and nothing was billed. stack: type: string enum: - none - slurm - kubernetes - ray stack_status: type: string enum: - pending - installing - ready - failed stack_detail: type: string nullable: true description: The last message from the installer, e.g. why it failed. node_count: type: integer description: Number of machines. gpu_type: type: string gpus_per_node: type: integer description: GPUs on each machine. deployment_type: type: string enum: - vm - baremetal - container host_tier: type: string enum: - datacenter - community location: type: string country_code: type: string description: ISO country code of the location, when it names a known country. interconnect: $ref: '#/components/schemas/ClusterInterconnect' hourly_rate_per_node: type: number description: USD per hour for one machine. hourly_rate: type: number description: >- USD per hour for the whole cluster: `hourly_rate_per_node` times `node_count`. created_at: type: string format: date-time up_at: type: string format: date-time nullable: true description: >- When every machine was up and joined. Billing starts here, for every machine at once. ready_at: type: string format: date-time nullable: true terminated_at: type: string format: date-time nullable: true failure_reason: type: string nullable: true description: Only when `status` is `failed`. failure_detail: type: string nullable: true description: Only when `status` is `failed`. ClusterNode: type: object required: - rank - role - instance_id - name - status - stage - overlay_address - gpus - ip - ssh_command properties: rank: type: integer description: Rank 0 is the head. role: type: string enum: - head - worker instance_id: type: string format: uuid description: >- The machine as an instance: `/instances/{id}/exec`, `/upload`, `/download` and `/ssh-certificate` take it. name: type: string example: train-1 status: type: string description: The machine's status, as on an instance. stage: type: string description: >- launching, machine_up, overlay_up, joined, stack_installing, stack_ready, stack_failed, test_result or drained. overlay_address: type: string nullable: true description: Its address on the private network, e.g. `10.77.0.2`. gpus: type: integer ip: type: string nullable: true description: >- Where SSH reaches it: its own address, or a gateway's when it has no public address of its own. `null` until the cluster is up. ssh_command: type: string nullable: true description: >- e.g. `ssh root@203.0.113.5`, with `-p` when SSH is not on 22. `null` until the cluster is up. ClusterTest: type: object description: An NCCL all-reduce test across every GPU of the cluster. required: - id - kind - status - started_at - finished_at - result properties: id: type: string format: uuid kind: type: string enum: - nccl_all_reduce status: type: string enum: - running - passed - failed started_at: type: string format: date-time finished_at: type: string format: date-time nullable: true result: type: object nullable: true properties: sizes: type: array items: type: object properties: bytes: type: integer algbw_gb_s: type: number busbw_gb_s: type: number time_us: type: number peak_busbw_gb_s: type: number nodes: type: integer gpus: type: integer error: type: string note: type: string description: Why the test stopped early on a slow link. ClusterInterconnect: type: object description: How the machines talk to each other. required: - kind - label properties: kind: type: string enum: - infiniband - roce - ethernet description: Self-serve clusters are `ethernet` today. rate_gbps: type: number description: Link rate per machine, when known. label: type: string description: What the dashboard shows, e.g. `Ethernet`. note: type: string description: >- What the link is good for, when it is not a training fabric. Every `ethernet` cluster has one. responses: Unauthorized: description: Missing or invalid API key. content: application/json: schema: $ref: '#/components/schemas/Error' securitySchemes: ApiKeyAuth: type: http scheme: bearer description: >- Use a Runcrate API key with the `rc_live_*` prefix as the bearer token. Create one at https://www.runcrate.ai/dashboard/api-keys. ```` This documentation is built and hosted on [Mintlify](https://mintlify.com), a developer documentation platform.