Trigger a pod state transition
Start, stop, or restart a Runpod Pod by sending a supported state transition action and retrieving the Pod’s updated lifecycle state.
Authorizations
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.
Body
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.
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.
"--model meta-llama/Llama-3-8B --max-model-len 8192"
"{\"entrypoint\":[\"/bin/bash\",\"-c\"],\"cmd\":[\"python -u main.py\"]}"
""
Lifecycle status of a pod.
PROVISIONING— pod is being allocatedSTARTING— container is startingRUNNING— container is healthyEXITED— container exited (stopped)ERROR— container is in an unrecoverable error stateTERMINATED— pod has been permanently deleted
PROVISIONING, STARTING, RUNNING, EXITED, ERROR, TERMINATED 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.
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.
"12.8"
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.