Sign in

v1

latestOpenAPI 3.1.02026-07-2676123203.9 KB
Pods

Create a pod

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.

post/v2/pods

Request body

imagestring required

Docker image reference

argsstring

Arguments passed to the container entrypoint

diskinteger

Container disk in GB (ephemeral, wiped on restart)

portsstring[]

Exposed ports, formatted as port/protocol

envobject

Environment variables as key-value pairs

registrystring nullable

Container registry credential ID (for private images)

namestring required
cloud'SECURE' | 'COMMUNITY'

Cloud tier.

  • SECURE — Runpod-owned datacenter hardware
  • COMMUNITY — community-hosted hardware
dataCenterIdsstring[]

Preferred data centers for placement. Omit or pass an empty array to let the scheduler choose.

globalNetworkingboolean

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.

Example request

{
  "image": "runpod/pytorch:2.8.0-py3.11-cuda12.8.1",
  "disk": 50,
  "ports": [
    "8888/http",
    "22/tcp"
  ],
  "env": {
    "JUPYTER_PASSWORD": "hunter2"
  },
  "name": "my-training-pod",
  "mounts": {
    "persistent": {
      "size": 20,
      "path": "/workspace"
    },
    "network": [
      {
        "volumeId": "vol_xyz",
        "path": "/runpod-volume"
      }
    ]
  },
  "gpu": {
    "id": "NVIDIA GeForce RTX 4090",
    "count": 1
  },
  "cpu": {
    "id": "cpu5c",
    "vcpuCount": 4
  },
  "dataCenterIds": [
    "US-TX-3"
  ]
}

Response

Created

adjustedCostPerHrnumber

The effective cost in Runpod credits per hour of running a Pod, adjusted by active Savings Plans.

aiApiIdstring

Synonym for endpointId (legacy name).

consumerUserIdstring

A unique string identifying the Runpod user who rents a Pod.

containerDiskInGbinteger

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.

containerRegistryAuthIdstring

If a Pod is created with a container registry auth, the unique string identifying that container registry auth.

costPerHrnumber

The cost in Runpod credits per hour of running a Pod. Note that the actual cost may be lower if Savings Plans are applied.

cpuFlavorIdstring

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.

dockerEntrypointstring[]

If specified, overrides the ENTRYPOINT for the Docker image run on the created Pod. If [], uses the ENTRYPOINT defined in the image.

dockerStartCmdstring[]

If specified, overrides the start CMD for the Docker image run on the created Pod. If [], uses the start CMD defined in the image.

endpointIdstring

If the Pod is a Serverless worker, a unique string identifying the associated endpoint.

envobject
idstring

A unique string identifying a Pod.

imagestring

The image tag for the container run on a Pod.

interruptibleboolean

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.

lastStartedAtstring

The UTC timestamp when a Pod was last started.

lastStatusChangestring

A string describing the last lifecycle event on a Pod.

lockedboolean

Set to true to lock a Pod. Locking a Pod disables stopping or resetting the Pod.

machineIdstring

A unique string identifying the host machine a Pod is running on.

memoryInGbnumber

The amount of RAM, in gigabytes (GB), attached to a Pod.

namestring

A user-defined name for the created Pod. The name does not need to be unique.

portMappingsobject 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.

portsstring[]

A list of ports exposed on a Pod. Each port is formatted as [port number]/[protocol]. Protocol can be either http or tcp.

publicIpstring 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.

slsVersioninteger

If the Pod is a Serverless worker, the version of the associated endpoint (see Endpoint Version).

templateIdstring

If a Pod is created with a template, the unique string identifying that template.

vcpuCountnumber

The number of virtual CPUs attached to a Pod.

volumeEncryptedboolean

Set to true if the local network volume of a Pod is encrypted. Can only be set when creating a Pod.

volumeInGbinteger

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.

volumeMountPathstring

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.

Example response

{
  "adjustedCostPerHr": 0.69,
  "consumerUserId": "user_2PyTJrLzeuwfZilRZ7JhCQDuSqo",
  "containerDiskInGb": 50,
  "containerRegistryAuthId": "clzdaifot0001l90809257ynb",
  "cpuFlavorId": "cpu3c",
  "env": {
    "ENV_VAR": "value"
  },
  "gpu": {
    "count": 1
  },
  "id": "xedezhzb9la3ye",
  "image": "runpod/pytorch:2.1.0-py3.10-cuda11.8.0-devel-ubuntu22.04",
  "lastStartedAt": "2024-07-12T19:14:40.144Z",
  "lastStatusChange": "Rented by User: Fri Jul 12 2024 15:14:40 GMT-0400 (Eastern Daylight Time)",
  "machine": {
    "gpuType": {
      "count": 1
    }
  },
  "machineId": "s194cr8pls2z",
  "memoryInGb": 62,
  "networkVolume": {
    "id": "agv6w2qcg7",
    "name": "my network volume",
    "size": 50,
    "dataCenterId": "EU-RO-1"
  },
  "portMappings": {
    "22": 10341
  },
  "ports": [
    "8888/http",
    "22/tcp"
  ],
  "publicIp": "100.65.0.119",
  "savingsPlans": [
    {
      "costPerHr": 0.21,
      "endTime": "2024-07-12T19:14:40.144Z",
      "gpuTypeId": "NVIDIA GeForce RTX 4090",
      "id": "clkrb4qci0000mb09c7sualzo",
      "podId": "xedezhzb9la3ye",
      "startTime": "2024-05-12T19:14:40.144Z"
    }
  ],
  "vcpuCount": 24,
  "volumeInGb": 20,
  "volumeMountPath": "/workspace"
}