---
title: "Trigger a pod state transition"
method: POST
path: "/v2/pods/{id}/action"
tags: ["Pods"]
---

# Trigger a pod state transition

`POST /v2/pods/{id}/action`

Triggers a state transition on a pod. Send a JSON body with a single
`action` field, e.g. `{ "action": "stop" }`.

Valid actions:
- `start`     — boot a stopped pod (`EXITED` or `ERROR`) back toward
  `RUNNING`.
- `stop`      — stop a running or provisioning pod, releasing GPU/CPU
  compute while keeping its disk. The pod moves to `EXITED`.
- `restart`   — restart a `RUNNING` pod's container in place.
- `terminate` — permanently delete the pod and release its resources
  (equivalent to `deletePod`).

Which actions are valid depends on the pod's current status, and the
currently permitted set is published in the pod's `actions` field:
`RUNNING` allows `stop`/`restart`/`terminate`; `EXITED` and `ERROR`
allow `start`/`terminate`; `PROVISIONING` and `STARTING` allow
`stop`/`terminate`.

`start`, `stop`, and `restart` return `200` with the updated pod.
`terminate` returns `204` with no body. Requesting an action that is
not valid for the pod's current status returns `409`.

## Request body

- PodActionRequest
  - `action` 'start' | 'stop' | 'restart' | 'terminate', required — State transition to trigger on a pod.

## Response `200`

Action applied — returns updated pod

- 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

- `204` — Only returned when `action=terminate`; response has no body.
- `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.
- `404` — The requested resource was not found or is not accessible to the caller.
- `409` — Action not valid for current pod status
- `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)