> ## Documentation Index
> Fetch the complete documentation index at: https://docs.runpod.io/llms.txt
> Use this file to discover all available pages before exploring further.

# Get a cluster

> Returns a single cluster by ID. The pods field is an aggregate summary (total + count by status); fetch the member pods themselves from /v2/clusters/{id}/pods.



## OpenAPI

````yaml get /v2/clusters/{id}
openapi: 3.1.0
info:
  title: Runpod REST API
  version: 2.0.0
  description: Runpod public REST API — v2
servers:
  - url: https://api.runpod.io
    description: Runpod API v2 production server
security:
  - bearerAuth: []
tags:
  - name: Account
    description: Account-scoped settings and primitives (SSH public keys).
  - name: Pods
    description: GPU and CPU pod lifecycle, configuration, actions, and log streaming.
  - name: Serverless
    description: >-
      Serverless endpoint lifecycle, worker visibility, releases, and worker log
      streaming.
  - name: Templates
    description: Reusable pod and endpoint configuration templates.
  - name: Network Volumes
    description: Persistent network storage volumes for workloads.
  - name: Registries
    description: Container registry credentials used to pull private images.
  - name: Catalog
    description: Available GPU, CPU, data center, and public template catalog metadata.
  - name: Billing
    description: Billing history and usage cost records across resource types.
paths:
  /v2/clusters/{id}:
    parameters:
      - name: id
        in: path
        required: true
        schema:
          type: string
        description: Cluster identifier
        example: cluster_abc123
    get:
      tags:
        - Clusters
      summary: Get a cluster
      description: >-
        Returns a single cluster by ID. The pods field is an aggregate summary
        (total + count by status); fetch the member pods themselves from
        /v2/clusters/{id}/pods.
      operationId: getCluster
      responses:
        '200':
          description: OK
          content:
            application/json:
              schema:
                $ref: '#/components/schemas/Cluster'
        '401':
          $ref: '#/components/responses/UnauthorizedError'
        '403':
          $ref: '#/components/responses/ForbiddenError'
        '404':
          description: Cluster not found
          content:
            application/problem+json:
              schema:
                $ref: '#/components/schemas/ErrorResponse'
        '429':
          $ref: '#/components/responses/TooManyRequestsError'
        default:
          description: Error
          content:
            application/problem+json:
              schema:
                $ref: '#/components/schemas/ErrorResponse'
components:
  schemas:
    Cluster:
      type: object
      description: >-
        A cluster. Cluster-level fields describe the identity and homogeneous
        shape; `pods` is a lightweight summary of the members. Fetch the full
        member pods — with their container config, mounts, and runtime state —
        from `GET /v2/clusters/{id}/pods`.
      required:
        - id
        - name
        - type
        - compute
        - pods
        - createdAt
      properties:
        id:
          type: string
          examples:
            - cluster_abc123
        name:
          type: string
          examples:
            - my-training-cluster
        type:
          $ref: '#/components/schemas/ClusterType'
        compute:
          $ref: '#/components/schemas/ClusterCompute'
        template:
          type: string
          description: >-
            ID of the template this cluster's pods were created from; omitted
            when they were not created from one.
          examples:
            - tpl_abc
        dataCenterId:
          type: string
          description: >-
            Data center the cluster is placed in (a cluster is always within a
            single data center). Derived from the member pods; omitted until at
            least one pod is placed.
          examples:
            - US-TX-3
        pods:
          $ref: '#/components/schemas/ClusterPodsSummary'
        network:
          description: >-
            The cluster's overlay network; omitted until the network is
            provisioned.
          allOf:
            - $ref: '#/components/schemas/ClusterNetwork'
        primary:
          description: >-
            The primary (master) node; omitted until a primary pod is placed.
            Its `sshEndpoint` is omitted until that pod is RUNNING with SSH
            exposed.
          allOf:
            - $ref: '#/components/schemas/ClusterPrimary'
        createdAt:
          type: string
          format: date-time
          examples:
            - '2026-06-29T20:00:00Z'
    ErrorResponse:
      type: object
      required:
        - title
        - status
        - detail
      properties:
        title:
          type: string
          description: Short human-readable summary
          examples:
            - Not Found
        status:
          type: integer
          description: HTTP status code
          examples:
            - 404
        detail:
          type: string
          description: Human-readable explanation
          examples:
            - pod not found
        errors:
          type: array
          description: Individual request-validation failures.
          items:
            type: string
          examples:
            - - '$: additional properties ''bogus'' not allowed'
    ClusterType:
      type: string
      description: >-
        Cluster type. TRAINING is the generic distributed-training cluster;
        SLURM provisions a managed Slurm controller/compute topology; RAY
        provisions a managed Ray head/worker topology; APPLICATION is a general
        multi-node application cluster.
      enum:
        - APPLICATION
        - TRAINING
        - SLURM
        - RAY
      examples:
        - TRAINING
    ClusterCompute:
      type: object
      additionalProperties: false
      description: >-
        The homogeneous compute shape of a cluster. Every pod in the cluster is
        identical: `podCount` pods, each with `gpuCountPerPod` GPUs of type
        `gpuTypeId`. Total GPUs = `podCount` * `gpuCountPerPod`.
      required:
        - gpuTypeId
        - gpuCountPerPod
        - podCount
      properties:
        gpuTypeId:
          type: string
          minLength: 1
          description: >-
            GPU type for every pod in the cluster, as returned by GET
            /v2/catalog/gpus.
          examples:
            - NVIDIA H100 80GB HBM3
        gpuCountPerPod:
          type: integer
          minimum: 1
          description: >-
            Number of GPUs on each pod. Bounded above by the GPU type's
            per-cloud maximum (GpuType.maxCount); the upstream rejects values
            beyond it.
          examples:
            - 8
        podCount:
          type: integer
          minimum: 2
          maximum: 250
          description: Number of pods (nodes) in the cluster.
          examples:
            - 4
    ClusterPodsSummary:
      type: object
      additionalProperties: false
      description: >-
        A lightweight summary of a cluster's member pods. Use `GET
        /v2/clusters/{id}/pods` to retrieve the full pod objects.
      required:
        - total
        - byStatus
      properties:
        total:
          type: integer
          description: Number of member pods currently provisioned for the cluster.
          examples:
            - 4
        byStatus:
          type: object
          additionalProperties:
            type: integer
          description: >-
            Member pod counts keyed by pod status (the same values as
            `Pod.status`, e.g. RUNNING, PROVISIONING). Statuses with no pods are
            omitted.
          example:
            RUNNING: 3
            PROVISIONING: 1
    ClusterNetwork:
      type: object
      additionalProperties: false
      description: The cluster's private VXLAN overlay network (shared by all member pods).
      required:
        - cidr
      properties:
        cidr:
          type: string
          description: The overlay network's CIDR block.
          examples:
            - 10.65.0.0/16
        vxlanId:
          type: integer
          description: VXLAN network identifier; omitted until assigned.
          examples:
            - 42
        vxlanPort:
          type: integer
          description: UDP port carrying the VXLAN traffic; omitted until assigned.
          examples:
            - 4789
    ClusterPrimary:
      type: object
      additionalProperties: false
      description: >-
        The cluster's primary (master) node, through which the cluster is
        typically driven. Omitted until a primary pod has been placed.
      required:
        - podId
        - status
      properties:
        podId:
          type: string
          description: ID of the primary member pod.
          examples:
            - pod_node0
        status:
          $ref: '#/components/schemas/PodStatus'
        sshEndpoint:
          type: string
          description: >-
            Public SSH endpoint (`host:port`) for the primary node; omitted when
            the primary is not yet RUNNING or does not expose SSH (22/tcp).
          examples:
            - 1.2.3.4:22001
    PodStatus:
      type: string
      description: |
        Lifecycle status of a pod.
        - `PROVISIONING` — pod is being allocated
        - `STARTING`     — container is starting
        - `RUNNING`      — container is healthy
        - `EXITED`       — container exited (stopped)
        - `ERROR`        — container is in an unrecoverable error state
        - `TERMINATED`   — pod has been permanently deleted
      enum:
        - PROVISIONING
        - STARTING
        - RUNNING
        - EXITED
        - ERROR
        - TERMINATED
    RateLimitHeader:
      type: string
      description: |
        Live per-window quota state. Optional — omitted for rate-limit-exempt
        callers.

        A structured-field list with one member per window (`minute`, `hour`,
        `day`), each carrying the remaining request count `r` and seconds until
        the window resets `t`. Returned on responses to authenticated requests,
        not only on 429s.
      examples:
        - '"minute";r=0;t=12, "hour";r=2800;t=1812, "day";r=49500;t=45012'
    RateLimitPolicyHeader:
      type: string
      description: >
        Static per-window quota policy. Optional — omitted for rate-limit-exempt

        callers.


        A structured-field list with one member per window (`minute`, `hour`,

        `day`), each carrying the quota `q` and the window length in seconds
        `w`.

        Returned on responses to authenticated requests, not only on 429s.
      examples:
        - '"minute";q=60;w=60, "hour";q=3000;w=3600, "day";q=50000;w=86400'
  responses:
    UnauthorizedError:
      description: >-
        Authentication failed because the bearer token is missing, malformed,
        expired, or invalid.
      content:
        application/problem+json:
          schema:
            $ref: '#/components/schemas/ErrorResponse'
          examples:
            missingBearerToken:
              summary: Missing bearer token
              value:
                title: Unauthorized
                status: 401
                detail: missing bearer token
    ForbiddenError:
      headers:
        RateLimit:
          $ref: '#/components/headers/RateLimit'
        RateLimit-Policy:
          $ref: '#/components/headers/RateLimit-Policy'
      description: >-
        The bearer token is valid, but it does not grant access to the requested
        resource or action.
      content:
        application/problem+json:
          schema:
            $ref: '#/components/schemas/ErrorResponse'
          examples:
            insufficientAccess:
              summary: Insufficient access
              value:
                title: Forbidden
                status: 403
                detail: access denied
    TooManyRequestsError:
      description: >
        The caller exceeded its per-user rate limit. The response identifies the
        window that was exceeded and how long to wait. The `RateLimit` and
        `RateLimit-Policy` headers (per the IETF ratelimit-headers draft) also
        accompany successful responses, so clients can track quota before a 429.
      headers:
        Retry-After:
          description: Seconds to wait before retrying, per the exceeded window.
          schema:
            type: integer
          example: 12
        RateLimit:
          $ref: '#/components/headers/RateLimit'
        RateLimit-Policy:
          $ref: '#/components/headers/RateLimit-Policy'
      content:
        application/problem+json:
          schema:
            $ref: '#/components/schemas/ErrorResponse'
          examples:
            rateLimited:
              summary: Rate limit exceeded
              value:
                title: Too Many Requests
                status: 429
                detail: rate limit exceeded for the minute window
  headers:
    RateLimit:
      schema:
        $ref: '#/components/schemas/RateLimitHeader'
    RateLimit-Policy:
      schema:
        $ref: '#/components/schemas/RateLimitPolicyHeader'
  securitySchemes:
    bearerAuth:
      type: http
      scheme: bearer
      bearerFormat: Runpod API Key
      description: >
        Runpod API key authentication. Generate an API key in the Runpod console
        and send it in the `Authorization` header as `Bearer <api_key>`. Keys
        are scoped to the permissions granted when created; requests may return
        `403` when a valid key lacks access to the requested resource or action.

````