---
title: "Create a pod"
method: POST
path: "/v2/pods"
tags: ["Pods"]
---

# Create a pod

`POST /v2/pods`

Creates a new pod. `name` and `image` are always required; supply
exactly one of `gpu` or `cpu` to select compute (a GPU or a CPU pod).
Remaining container settings can be spread from a template response —
see `CreatePodRequest` for the full body.

Returns `201` with the created pod. Provisioning is asynchronous: the
pod starts in `PROVISIONING`, transitions through `STARTING`, and
reaches `RUNNING` once its container is healthy. Poll `getPod` (or
watch the pod's `status`) to observe readiness rather than assuming
the pod is running when this call returns.

## Request body

- CreatePodRequest — Request body for creating a pod. Exactly one of `gpu` or `cpu` must be set — enforced at the handler layer. For CPU pods, memory is derived by the API from the selected flavor's RAM multiplier; clients provide only CPU flavor and vCPU count. CPU pods support container disk and network volumes only; `mounts.persistent` is invalid when `cpu` is set.
  - `image` string, required — Docker image reference
  - `args` string — Arguments passed to the container entrypoint
  - `disk` integer — Container disk in GB (ephemeral, wiped on restart)
  - `ports` string[] — Exposed ports, formatted as port/protocol
  - `env` object — Environment variables as key-value pairs
  - `registry` string, nullable — Container registry credential ID (for private images)
  - `name` string, required
  - `mounts` Mounts — Storage mounts attached to a pod. At-most-one of `persistent` or `network` may be set today (mutually exclusive, enforced at the handler with 400 if both are present). The `network` field is an array for forward compatibility with eventual multi-network-volume support, but `maxItems` is 1 today. PATCH semantics: - Omitting `mounts` or sending `{}` leaves the existing mount unchanged. - An explicit `network: []` is rejected with 400 (clearing mounts is not supported). - Mount kind is fixed at create — a PATCH that introduces a kind not present at create (persistent on a network pod, network on a persistent pod, or any mount on a previously-mountless pod) is rejected with 400. - The `volumeId` of a network mount is immutable; a PATCH that names a different `volumeId` is rejected with 400. - Partial mounts are not supported — every mount entry must include the full schema (`size` + `path` for persistent, `volumeId` + `path` for network). Missing required fields → 422.
    - `persistent` PersistentMount — Host-local persistent storage. Pinned to the pod's host machine — data does not survive a host failure. Disallowed on CPU pods. Mutually exclusive with NetworkMount. Deprecated: prefer NetworkMount for any data you cannot recreate.
      - `size` integer, required — Host-local persistent storage in GB. Upstream enforces a 10 GB floor.
      - `path` string, required — Mount path inside the container. May be changed via PATCH.
    - `network` NetworkMount[]
      - `volumeId` string, required — ID of an existing NetworkVolume in the same data center as the pod.
      - `path` string, required — Mount path inside the container. No default — must be specified explicitly.
  - `gpu` GpuConfig
    - `id` string, required — GPU type identifier
    - `count` integer — Number of GPUs
  - `cpu` CreateCpuConfig
    - `id` string, required — CPU flavor identifier, as returned by GET /v2/catalog/cpus.
    - `vcpuCount` integer, required — Number of vCPUs. Must be valid for the selected CPU flavor and must be a power of two.
  - `cloud` 'SECURE' | 'COMMUNITY' — Cloud tier. - `SECURE` — Runpod-owned datacenter hardware - `COMMUNITY` — community-hosted hardware
  - `dataCenterIds` string[] — Preferred data centers for placement. Omit or pass an empty array to let the scheduler choose.
  - `globalNetworking` boolean — Enable global networking, giving the pod a private IP reachable across data centers. Requires an NVIDIA GPU and a global-networking-enabled data center (both enforced upstream). See `GET /v2/catalog/datacenters` (`globalNetwork`) for eligible data centers.

## Response `201`

Created

- Pod
  - `adjustedCostPerHr` number — The effective cost in Runpod credits per hour of running a Pod, adjusted by active Savings Plans.
  - `aiApiId` string — Synonym for endpointId (legacy name).
  - `consumerUserId` string — A unique string identifying the Runpod user who rents a Pod.
  - `containerDiskInGb` integer — The amount of disk space, in gigabytes (GB), to allocate on the container disk for a Pod. The data on the container disk is wiped when the Pod restarts. To persist data across Pod restarts, set volumeInGb to configure the Pod network volume.
  - `containerRegistryAuthId` string — If a Pod is created with a container registry auth, the unique string identifying that container registry auth.
  - `costPerHr` number — The cost in Runpod credits per hour of running a Pod. Note that the actual cost may be lower if Savings Plans are applied.
  - `cpuFlavorId` string — If the Pod is a CPU Pod, the unique string identifying the CPU flavor the Pod is running on.
  - `desiredStatus` 'RUNNING' | 'EXITED' | 'TERMINATED' — The current expected status of a Pod.
  - `dockerEntrypoint` string[] — If specified, overrides the ENTRYPOINT for the Docker image run on the created Pod. If [], uses the ENTRYPOINT defined in the image.
  - `dockerStartCmd` string[] — If specified, overrides the start CMD for the Docker image run on the created Pod. If [], uses the start CMD defined in the image.
  - `endpointId` string — If the Pod is a Serverless worker, a unique string identifying the associated endpoint.
  - `env` object
  - `gpu` object
    - `id` string
    - `count` integer — The number of GPUs attached to a Pod.
    - `displayName` string
    - `securePrice` number
    - `communityPrice` number
    - `oneMonthPrice` number
    - `threeMonthPrice` number
    - `sixMonthPrice` number
    - `oneWeekPrice` number
    - `communitySpotPrice` number
    - `secureSpotPrice` number
  - `id` string — A unique string identifying a [Pod](#/components/schema/Pod).
  - `image` string — The image tag for the container run on a Pod.
  - `interruptible` boolean — Describes how a Pod is rented. An interruptible Pod can be rented at a lower cost but can be stopped at any time to free up resources for another Pod. A reserved Pod is rented at a higher cost but runs until it exits or is manually stopped.
  - `lastStartedAt` string — The UTC timestamp when a Pod was last started.
  - `lastStatusChange` string — A string describing the last lifecycle event on a Pod.
  - `locked` boolean — Set to true to lock a Pod. Locking a Pod disables stopping or resetting the Pod.
  - `machine` object — Information about the machine a Pod is running on (see [Machine](#/components/schemas/Machine)).
    - `minPodGpuCount` integer
    - `gpuTypeId` string
    - `gpuType` object
      - `id` string
      - `count` integer — The number of GPUs attached to a Pod.
      - `displayName` string
      - `securePrice` number
      - `communityPrice` number
      - `oneMonthPrice` number
      - `threeMonthPrice` number
      - `sixMonthPrice` number
      - `oneWeekPrice` number
      - `communitySpotPrice` number
      - `secureSpotPrice` number
    - `cpuCount` integer
    - `cpuTypeId` string
    - `cpuType` object
      - `id` string
      - `displayName` string
      - `cores` number
      - `threadsPerCore` number
      - `groupId` string
    - `location` string
    - `dataCenterId` string
    - `diskThroughputMBps` integer
    - `maxDownloadSpeedMbps` integer
    - `maxUploadSpeedMbps` integer
    - `supportPublicIp` boolean
    - `secureCloud` boolean
    - `maintenanceStart` string
    - `maintenanceEnd` string
    - `maintenanceNote` string
    - `note` string
    - `costPerHr` number
    - `currentPricePerGpu` number
    - `gpuAvailable` integer
    - `gpuDisplayName` string
  - `machineId` string — A unique string identifying the host machine a Pod is running on.
  - `memoryInGb` number — The amount of RAM, in gigabytes (GB), attached to a Pod.
  - `name` string — A user-defined name for the created Pod. The name does not need to be unique.
  - `networkVolume` object — If a network volume is attached to a Pod, information about the network volume (see [network volume schema](#/components/schemas/NetworkVolume)).
    - `id` string — A unique string identifying a network volume.
    - `name` string — A user-defined name for a network volume. The name does not need to be unique.
    - `size` integer — The amount of disk space, in gigabytes (GB), allocated to a network volume.
    - `dataCenterId` string — The Runpod data center ID where a network volume is located.
  - `portMappings` object, nullable — A mapping of internal ports to public ports on a Pod. For example, { "22": 10341 } means that port 22 on the Pod is mapped to port 10341 and is publicly accessible at [public ip]:10341. If the Pod is still initializing, this mapping is not yet determined and will be empty.
  - `ports` string[] — A list of ports exposed on a Pod. Each port is formatted as [port number]/[protocol]. Protocol can be either http or tcp.
  - `publicIp` string, ipv4, nullable — The public IP address of a Pod. If the Pod is still initializing, this IP is not yet determined and will be empty.
  - `savingsPlans` SavingsPlan[] — The list of active Savings Plans applied to a Pod (see [Savings Plans](#/components/schemas/SavingsPlan)). If none are applied, the list is empty.
    - `costPerHr` number
    - `endTime` string
    - `gpuTypeId` string
    - `id` string
    - `podId` string
    - `startTime` string
  - `slsVersion` integer — If the Pod is a Serverless worker, the version of the associated endpoint (see [Endpoint Version](#/components/schemas/Endpoint/version)).
  - `templateId` string — If a Pod is created with a template, the unique string identifying that template.
  - `vcpuCount` number — The number of virtual CPUs attached to a Pod.
  - `volumeEncrypted` boolean — Set to true if the local network volume of a Pod is encrypted. Can only be set when creating a Pod.
  - `volumeInGb` integer — The amount of disk space, in gigabytes (GB), to allocate on the Pod volume for a Pod. The data on the Pod volume is persisted across Pod restarts. To persist data so that future Pods can access it, create a network volume and set networkVolumeId to attach it to the Pod.
  - `volumeMountPath` string — If either a Pod volume or a network volume is attached to a Pod, the absolute path where the network volume is mounted in the filesystem.

## Other responses

- `400` — The request could not be processed because it is malformed or conflicts with request rules.
- `401` — Authentication failed because the bearer token is missing, malformed, expired, or invalid.
- `403` — The bearer token is valid, but it does not grant access to the requested resource or action.
- `422` — The request body or parameters were syntactically valid but failed validation.
- `429` — 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.
- `default` — Error

---

[API](https://skmtc.dev/runpod/apis/runpod-rest-api.md) · [All operations](https://skmtc.dev/runpod/apis/runpod-rest-api/llms.txt) · [OpenAPI document](https://skmtc-service-production.skmtc.workers.dev/v1/apis/runpod/runpod-rest-api/revisions/504cd0394ed6/schema)