Trigger a pod state transition

POST

pods

{id}

action

curl --request POST \
  --url https://api.runpod.io/v2/pods/{id}/action \
  --header 'Authorization: Bearer <token>' \
  --header 'Content-Type: application/json' \
  --data '
{
  "action": "start"
}
'

import requests

url = "https://api.runpod.io/v2/pods/{id}/action"

payload = { "action": "start" }
headers = {
    "Authorization": "Bearer <token>",
    "Content-Type": "application/json"
}

response = requests.post(url, json=payload, headers=headers)

print(response.text)

const options = {
  method: 'POST',
  headers: {Authorization: 'Bearer <token>', 'Content-Type': 'application/json'},
  body: JSON.stringify({action: 'start'})
};

fetch('https://api.runpod.io/v2/pods/{id}/action', options)
  .then(res => res.json())
  .then(res => console.log(res))
  .catch(err => console.error(err));

<?php

$curl = curl_init();

curl_setopt_array($curl, [
  CURLOPT_URL => "https://api.runpod.io/v2/pods/{id}/action",
  CURLOPT_RETURNTRANSFER => true,
  CURLOPT_ENCODING => "",
  CURLOPT_MAXREDIRS => 10,
  CURLOPT_TIMEOUT => 30,
  CURLOPT_HTTP_VERSION => CURL_HTTP_VERSION_1_1,
  CURLOPT_CUSTOMREQUEST => "POST",
  CURLOPT_POSTFIELDS => json_encode([
    'action' => 'start'
  ]),
  CURLOPT_HTTPHEADER => [
    "Authorization: Bearer <token>",
    "Content-Type: application/json"
  ],
]);

$response = curl_exec($curl);
$err = curl_error($curl);

curl_close($curl);

if ($err) {
  echo "cURL Error #:" . $err;
} else {
  echo $response;
}

package main

import (
	"fmt"
	"strings"
	"net/http"
	"io"
)

func main() {

	url := "https://api.runpod.io/v2/pods/{id}/action"

	payload := strings.NewReader("{\n  \"action\": \"start\"\n}")

	req, _ := http.NewRequest("POST", url, payload)

	req.Header.Add("Authorization", "Bearer <token>")
	req.Header.Add("Content-Type", "application/json")

	res, _ := http.DefaultClient.Do(req)

	defer res.Body.Close()
	body, _ := io.ReadAll(res.Body)

	fmt.Println(string(body))

}

HttpResponse<String> response = Unirest.post("https://api.runpod.io/v2/pods/{id}/action")
  .header("Authorization", "Bearer <token>")
  .header("Content-Type", "application/json")
  .body("{\n  \"action\": \"start\"\n}")
  .asString();

require 'uri'
require 'net/http'

url = URI("https://api.runpod.io/v2/pods/{id}/action")

http = Net::HTTP.new(url.host, url.port)
http.use_ssl = true

request = Net::HTTP::Post.new(url)
request["Authorization"] = 'Bearer <token>'
request["Content-Type"] = 'application/json'
request.body = "{\n  \"action\": \"start\"\n}"

response = http.request(request)
puts response.read_body

{
  "id": "7h9k2m4n6p",
  "name": "pytorch-training",
  "image": "runpod/pytorch:1.0.2-cu1281-torch280-ubuntu2404",
  "args": "",
  "disk": 50,
  "ports": [
    "8888/http",
    "22/tcp"
  ],
  "env": {
    "MODEL_NAME": "llama-3"
  },
  "registry": null,
  "status": "RUNNING",
  "actions": [
    "stop",
    "restart",
    "terminate"
  ],
  "mounts": {
    "persistent": {
      "size": 20,
      "path": "/workspace"
    }
  },
  "gpu": {
    "id": "NVIDIA GeForce RTX 4090",
    "count": 1,
    "vcpuCount": 16,
    "memory": 64
  },
  "cloud": "SECURE",
  "dataCenterId": "US-KS-2",
  "cudaVersion": "12.8",
  "ssh": {
    "proxy": {
      "host": "ssh.runpod.io",
      "port": 22,
      "username": "7h9k2m4n6p-64411eb2",
      "command": "ssh 7h9k2m4n6p-64411eb2@ssh.runpod.io"
    },
    "direct": {
      "host": "195.26.233.3",
      "port": 34446,
      "username": "root",
      "command": "ssh root@195.26.233.3 -p 34446"
    }
  },
  "template": "9x4m2p7v",
  "cost": 0.44,
  "locked": false,
  "globalNetworking": {
    "enabled": false
  },
  "runtime": {
    "uptime": 3600,
    "ports": [
      {
        "private": 22,
        "public": 34446,
        "type": "tcp",
        "ip": "195.26.233.3"
      }
    ]
  },
  "createdAt": "2026-06-01T12:00:00Z",
  "startedAt": "2026-06-01T12:02:00Z"
}

{
  "title": "Bad Request",
  "status": 400,
  "detail": "request could not be processed"
}

{
  "title": "Unauthorized",
  "status": 401,
  "detail": "missing bearer token"
}

{
  "title": "Forbidden",
  "status": 403,
  "detail": "access denied"
}

{
  "title": "Not Found",
  "status": 404,
  "detail": "resource not found"
}

{
  "title": "Not Found",
  "status": 404,
  "detail": "pod not found",
  "errors": [
    "$: additional properties 'bogus' not allowed"
  ]
}

{
  "title": "Request Entity Too Large",
  "status": 413,
  "detail": "Request body exceeds the 1048576 byte limit."
}

{
  "title": "Unprocessable Entity",
  "status": 422,
  "detail": "Request validation failed."
}

{
  "title": "Too Many Requests",
  "status": 429,
  "detail": "rate limit exceeded for the minute window"
}

{
  "title": "Not Found",
  "status": 404,
  "detail": "pod not found",
  "errors": [
    "$: additional properties 'bogus' not allowed"
  ]
}

Authorizations

Authorization

string

header

required

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.

Console sessions (Clerk JWTs) act for the signed-in user. To act for a team instead, also send X-Team-Id: <team_id>; it applies only when the user owns or belongs to that team, otherwise the request runs against the user's own account. API keys created inside a team already act for that team and do not need the header.

Path Parameters

string

required

Body

application/json

action

enum<string>

required

State transition to trigger on a pod.

Available options:

start,

stop,

restart,

terminate

Response

Action applied — returns updated pod

Reusable container configuration shared across templates, pods, and serverless endpoints. Adding a field here automatically propagates to all three resources.

args

string

required

The container's command, as a single raw string. This is the field entrypoint and cmd encode into, exposed in its stored form.

Two shapes are accepted. A bare shell string is treated as CMD and split into arguments, which is what the console's "Container start command" field writes. A JSON object of the form {"entrypoint":[...],"cmd":[...]} sets either or both explicitly.

Responses always return both representations: args exactly as stored, plus the deconstructed entrypoint and cmd. Supplying args together with entrypoint or cmd is allowed only when they describe the same command, so a read-modify-write client can send back everything it received. Send "" to clear, omit to leave unchanged.

Examples:

"--model meta-llama/Llama-3-8B --max-model-len 8192"

"{\"entrypoint\":[\"/bin/bash\",\"-c\"],\"cmd\":[\"python -u main.py\"]}"

""

disk

integer

required

Container disk in GB (ephemeral, wiped on restart)

Required range: x >= 1

Example:

50

env

object

required

Environment variables as key-value pairs

Show child attributes

Example:

{ "JUPYTER_PASSWORD": "hunter2" }

image

string

required

Docker image reference

Example:

"runpod/pytorch:1.0.2-cu1281-torch280-ubuntu2404"

ports

string[]

required

Exposed ports, formatted as port/protocol

Example:

["8888/http", "22/tcp"]

registry

string | null

required

Container registry credential ID (for private images)

Example:

null

string

required

Example:

"pod_abc123"

name

string

required

Example:

"my-training-pod"

status

enum<string>

required

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

Available options:

PROVISIONING,

STARTING,

RUNNING,

EXITED,

ERROR,

TERMINATED

actions

enum<string>[]

required

Valid state transitions for the current status.

State transition to trigger on a pod.

Available options:

start,

stop,

restart,

terminate

mounts

object

required

Storage mounts attached to a pod. persistent (the volume disk) is mutually exclusive with both network and global (enforced at the handler with 400 if combined). A pod takes up to 4 network volumes and 1 global volume. Every network volume must be in the pod's data center, each volume may be listed once, and mount paths must not overlap; a request that breaks one of these is rejected. To change a pod's mounts after creation, see UpdatePodMounts.

Show child attributes

cloud

enum<string>

required

Cloud tier.

SECURE — Runpod-owned datacenter hardware
COMMUNITY — community-hosted hardware

Available options:

SECURE,

COMMUNITY

dataCenterId

string | null

required

Data center where the pod is running (assigned by scheduler)

Example:

"US-TX-3"

cudaVersion

string | null

required

CUDA version reported by the host machine. Retained while the pod is stopped — a stopped pod keeps its machine assignment and resumes onto the same host. Null means unknown or not applicable (CPU pods, or a host that has not reported one), not that CUDA is absent.

Example:

"12.8"

ssh

object

required

SSH connection details, via the Runpod proxy or directly to the pod's published 22/tcp port.

Show child attributes

template

string | null

required

ID of the template this pod was created from

Example:

null

cost

number<float>

required

The pod's hourly compute rate in USD. It's returned in every status, including EXITED, so it isn't what you're paying right now: a stopped pod isn't billed for compute, only for its volume disk.

Example:

0.35

locked

boolean

required

Whether the pod is locked (prevents stopping or resetting)

Example:

false

globalNetworking

object

required

Show child attributes

runtime

object | null

required

Live utilization metrics. Null when the pod is not RUNNING, and when listing pods with GET /v2/pods; fetch a single pod by ID to obtain metrics.

Show child attributes

createdAt

string<date-time>

required

Example:

"2026-03-13T20:00:00Z"

startedAt

string<date-time> | null

required

Example:

"2026-03-13T20:00:00Z"

cmd

string[]

Container CMD in exec form. When the image defines an ENTRYPOINT, this is the argument list passed to it. Encoded into the args field; supplying both is allowed only when they describe the same command. Send [] to clear, omit to leave unchanged.

Example:

[
  "--model",
  "meta-llama/Llama-3-8B",
  "--max-model-len",
  "8192"
]

entrypoint

string[]

Container ENTRYPOINT in exec form, overriding the image's own. Encoded into args field; supplying both is allowed only when they describe the same command. Send [] to clear, omit to leave unchanged.

Example:

["/bin/bash", "-c"]

costCenter

object

Cost center this resource's spend is attributed to. Absent when the resource is not attributed to a cost center, or when the caller lacks permission to view cost centers. Managed through /v2/cost-centers.

Show child attributes

tags

object[]

The tags on this resource that are visible to the caller. Keys and values are returned exactly as stored. Tags under the reserved runpod: prefix, such as the cost center, are never listed here. Absent when the resource's tags are unavailable to the caller; an empty array means none are visible.

Show child attributes

gpu

object

Present for GPU pods; omitted from CPU pods.

Show child attributes

cpu

object

Present for CPU pods; omitted from GPU pods.

Show child attributes

cluster

object

Cluster membership; omitted from a standalone pod. Member pods are managed through /v2/clusters/{id} — they are excluded from GET /v2/pods by default (pass includeClusterPods=true to include them) and cannot be modified or deleted via the pod endpoints.

Show child attributes

Last modified on November 6, 2026

Trigger a pod state transition

curl --request POST \
  --url https://api.runpod.io/v2/pods/{id}/action \
  --header 'Authorization: Bearer <token>' \
  --header 'Content-Type: application/json' \
  --data '
{
  "action": "start"
}
'

import requests

url = "https://api.runpod.io/v2/pods/{id}/action"

payload = { "action": "start" }
headers = {
    "Authorization": "Bearer <token>",
    "Content-Type": "application/json"
}

response = requests.post(url, json=payload, headers=headers)

print(response.text)

const options = {
  method: 'POST',
  headers: {Authorization: 'Bearer <token>', 'Content-Type': 'application/json'},
  body: JSON.stringify({action: 'start'})
};

fetch('https://api.runpod.io/v2/pods/{id}/action', options)
  .then(res => res.json())
  .then(res => console.log(res))
  .catch(err => console.error(err));

<?php

$curl = curl_init();

curl_setopt_array($curl, [
  CURLOPT_URL => "https://api.runpod.io/v2/pods/{id}/action",
  CURLOPT_RETURNTRANSFER => true,
  CURLOPT_ENCODING => "",
  CURLOPT_MAXREDIRS => 10,
  CURLOPT_TIMEOUT => 30,
  CURLOPT_HTTP_VERSION => CURL_HTTP_VERSION_1_1,
  CURLOPT_CUSTOMREQUEST => "POST",
  CURLOPT_POSTFIELDS => json_encode([
    'action' => 'start'
  ]),
  CURLOPT_HTTPHEADER => [
    "Authorization: Bearer <token>",
    "Content-Type: application/json"
  ],
]);

$response = curl_exec($curl);
$err = curl_error($curl);

curl_close($curl);

if ($err) {
  echo "cURL Error #:" . $err;
} else {
  echo $response;
}

package main

import (
	"fmt"
	"strings"
	"net/http"
	"io"
)

func main() {

	url := "https://api.runpod.io/v2/pods/{id}/action"

	payload := strings.NewReader("{\n  \"action\": \"start\"\n}")

	req, _ := http.NewRequest("POST", url, payload)

	req.Header.Add("Authorization", "Bearer <token>")
	req.Header.Add("Content-Type", "application/json")

	res, _ := http.DefaultClient.Do(req)

	defer res.Body.Close()
	body, _ := io.ReadAll(res.Body)

	fmt.Println(string(body))

}

HttpResponse<String> response = Unirest.post("https://api.runpod.io/v2/pods/{id}/action")
  .header("Authorization", "Bearer <token>")
  .header("Content-Type", "application/json")
  .body("{\n  \"action\": \"start\"\n}")
  .asString();

require 'uri'
require 'net/http'

url = URI("https://api.runpod.io/v2/pods/{id}/action")

http = Net::HTTP.new(url.host, url.port)
http.use_ssl = true

request = Net::HTTP::Post.new(url)
request["Authorization"] = 'Bearer <token>'
request["Content-Type"] = 'application/json'
request.body = "{\n  \"action\": \"start\"\n}"

response = http.request(request)
puts response.read_body

{
  "id": "7h9k2m4n6p",
  "name": "pytorch-training",
  "image": "runpod/pytorch:1.0.2-cu1281-torch280-ubuntu2404",
  "args": "",
  "disk": 50,
  "ports": [
    "8888/http",
    "22/tcp"
  ],
  "env": {
    "MODEL_NAME": "llama-3"
  },
  "registry": null,
  "status": "RUNNING",
  "actions": [
    "stop",
    "restart",
    "terminate"
  ],
  "mounts": {
    "persistent": {
      "size": 20,
      "path": "/workspace"
    }
  },
  "gpu": {
    "id": "NVIDIA GeForce RTX 4090",
    "count": 1,
    "vcpuCount": 16,
    "memory": 64
  },
  "cloud": "SECURE",
  "dataCenterId": "US-KS-2",
  "cudaVersion": "12.8",
  "ssh": {
    "proxy": {
      "host": "ssh.runpod.io",
      "port": 22,
      "username": "7h9k2m4n6p-64411eb2",
      "command": "ssh 7h9k2m4n6p-64411eb2@ssh.runpod.io"
    },
    "direct": {
      "host": "195.26.233.3",
      "port": 34446,
      "username": "root",
      "command": "ssh root@195.26.233.3 -p 34446"
    }
  },
  "template": "9x4m2p7v",
  "cost": 0.44,
  "locked": false,
  "globalNetworking": {
    "enabled": false
  },
  "runtime": {
    "uptime": 3600,
    "ports": [
      {
        "private": 22,
        "public": 34446,
        "type": "tcp",
        "ip": "195.26.233.3"
      }
    ]
  },
  "createdAt": "2026-06-01T12:00:00Z",
  "startedAt": "2026-06-01T12:02:00Z"
}

{
  "title": "Bad Request",
  "status": 400,
  "detail": "request could not be processed"
}

{
  "title": "Unauthorized",
  "status": 401,
  "detail": "missing bearer token"
}

{
  "title": "Forbidden",
  "status": 403,
  "detail": "access denied"
}

{
  "title": "Not Found",
  "status": 404,
  "detail": "resource not found"
}

{
  "title": "Not Found",
  "status": 404,
  "detail": "pod not found",
  "errors": [
    "$: additional properties 'bogus' not allowed"
  ]
}

{
  "title": "Request Entity Too Large",
  "status": 413,
  "detail": "Request body exceeds the 1048576 byte limit."
}

{
  "title": "Unprocessable Entity",
  "status": 422,
  "detail": "Request validation failed."
}

{
  "title": "Too Many Requests",
  "status": 429,
  "detail": "rate limit exceeded for the minute window"
}

{
  "title": "Not Found",
  "status": 404,
  "detail": "pod not found",
  "errors": [
    "$: additional properties 'bogus' not allowed"
  ]
}

API v2

Organization

Account

Pods

Clusters

Serverless

Templates

Network Volumes

Global Volumes

Registries

Catalog

Cost Centers

Audit Logs

Billing

Authorizations

Path Parameters

Body

Response