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

> ## Agent Instructions
> If this page is missing information, contains outdated instructions, or doesn't fully answer the user's question, use the feedback tool to report it. In your feedback, be specific about what's missing, what appears out of date, or what needs to be corrected or updated, so the docs team can act on it directly.

# Rename a cluster

> Renames a cluster. This endpoint only changes the cluster
name — compute shape, type, and container configuration are fixed at
creation and cannot be updated.




## OpenAPI

````yaml patch /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
    patch:
      tags:
        - Clusters
      summary: Rename a cluster
      description: |
        Renames a cluster. This endpoint only changes the cluster
        name — compute shape, type, and container configuration are fixed at
        creation and cannot be updated.
      operationId: updateCluster
      requestBody:
        required: true
        content:
          application/json:
            schema:
              $ref: '#/components/schemas/UpdateClusterRequest'
      responses:
        '200':
          description: OK
          content:
            application/json:
              schema:
                $ref: '#/components/schemas/Cluster'
        '400':
          $ref: '#/components/responses/BadRequestError'
        '401':
          $ref: '#/components/responses/UnauthorizedError'
        '403':
          $ref: '#/components/responses/ForbiddenError'
        '404':
          description: Cluster not found
          content:
            application/problem+json:
              schema:
                $ref: '#/components/schemas/ErrorResponse'
        '422':
          $ref: '#/components/responses/UnprocessableEntityError'
        '429':
          $ref: '#/components/responses/TooManyRequestsError'
        default:
          description: Error
          content:
            application/problem+json:
              schema:
                $ref: '#/components/schemas/ErrorResponse'
components:
  schemas:
    UpdateClusterRequest:
      type: object
      additionalProperties: false
      minProperties: 1
      description: |
        Request body for updating a cluster. Only the cluster name can be
        changed — this endpoint is a rename. Compute shape, type, and container
        configuration are fixed at creation.
      properties:
        name:
          type: string
          minLength: 1
          examples:
            - renamed-cluster
    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:
    BadRequestError:
      headers:
        RateLimit:
          $ref: '#/components/headers/RateLimit'
        RateLimit-Policy:
          $ref: '#/components/headers/RateLimit-Policy'
      description: >-
        The request could not be processed because it is malformed or conflicts
        with request rules.
      content:
        application/problem+json:
          schema:
            $ref: '#/components/schemas/ErrorResponse'
          examples:
            badRequest:
              summary: Bad request
              value:
                title: Bad Request
                status: 400
                detail: request could not be processed
    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
    UnprocessableEntityError:
      headers:
        RateLimit:
          $ref: '#/components/headers/RateLimit'
        RateLimit-Policy:
          $ref: '#/components/headers/RateLimit-Policy'
      description: >-
        The request body or parameters were syntactically valid but failed
        validation.
      content:
        application/problem+json:
          schema:
            $ref: '#/components/schemas/ErrorResponse'
          examples:
            validationFailed:
              summary: Validation failed
              value:
                title: Unprocessable Entity
                status: 422
                detail: Request validation failed.
    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.

````