> ## Documentation Index > Fetch the complete documentation index at: https://docs.runpod.io/llms.txt > Use this file to discover all available pages before exploring further. # Trigger a pod state transition > 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`. ## OpenAPI ````yaml post /v2/pods/{id}/action openapi: 3.1.0 info: title: Runpod REST API version: 2.0.0 description: Runpod public REST API — v2 servers: - url: https://api.runpod.io description: Runpod API v2 production server security: - bearerAuth: [] tags: - name: Pods description: GPU and CPU pod lifecycle, configuration, actions, and log streaming. - name: Serverless description: >- Serverless endpoint lifecycle, worker visibility, releases, and worker log streaming. - name: Templates description: Reusable pod and endpoint configuration templates. - name: Network Volumes description: Persistent network storage volumes for workloads. - name: Registries description: Container registry credentials used to pull private images. - name: Catalog description: Available GPU, CPU, and data center catalog metadata. - name: Billing description: Billing history and usage cost records across resource types. paths: /v2/pods/{id}/action: parameters: - name: id in: path required: true schema: type: string example: pod_abc123 post: tags: - Pods summary: Trigger a pod state transition description: | 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`. operationId: podAction requestBody: required: true content: application/json: schema: $ref: '#/components/schemas/PodActionRequest' examples: startPod: summary: Start pod value: action: start responses: '200': description: Action applied — returns updated pod content: application/json: schema: $ref: '#/components/schemas/Pod' examples: pod: summary: Successful response value: id: 7h9k2m4n6p name: pytorch-training image: runpod/pytorch:2.8.0-py3.11-cuda12.8.1 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 cloud: SECURE dataCenterId: US-KS-2 template: 9x4m2p7v cost: 0.44 locked: false globalNetworking: enabled: false runtime: uptime: 3600 createdAt: '2026-06-01T12:00:00Z' startedAt: '2026-06-01T12:02:00Z' '204': description: Only returned when `action=terminate`; response has no body. '400': $ref: '#/components/responses/BadRequestError' '401': $ref: '#/components/responses/UnauthorizedError' '403': $ref: '#/components/responses/ForbiddenError' '404': $ref: '#/components/responses/NotFoundError' '409': description: Action not valid for current pod status content: application/problem+json: schema: $ref: '#/components/schemas/ErrorResponse' '422': $ref: '#/components/responses/UnprocessableEntityError' '429': $ref: '#/components/responses/TooManyRequestsError' default: description: Error content: application/problem+json: schema: $ref: '#/components/schemas/ErrorResponse' components: schemas: PodActionRequest: type: object additionalProperties: false required: - action properties: action: $ref: '#/components/schemas/PodAction' Pod: allOf: - $ref: '#/components/schemas/ContainerConfig' - type: object required: - id - name - status - actions - image - args - disk - mounts - ports - env - registry - cloud - dataCenterId - template - cost - locked - runtime - createdAt - startedAt - globalNetworking properties: id: type: string examples: - pod_abc123 name: type: string examples: - my-training-pod status: $ref: '#/components/schemas/PodStatus' actions: type: array description: Valid state transitions for the current status. items: $ref: '#/components/schemas/PodAction' mounts: $ref: '#/components/schemas/Mounts' gpu: description: Present for GPU pods; omitted from CPU pods. allOf: - $ref: '#/components/schemas/GpuConfig' cpu: description: Present for CPU pods; omitted from GPU pods. allOf: - $ref: '#/components/schemas/CpuConfig' cloud: $ref: '#/components/schemas/Cloud' dataCenterId: type: - string - 'null' description: Data center where the pod is running (assigned by scheduler) examples: - US-TX-3 template: type: - string - 'null' description: ID of the template this pod was created from examples: - null cost: type: number format: float description: Current cost in USD per hour (0.0 when EXITED or TERMINATED) examples: - 0.35 locked: type: boolean description: Whether the pod is locked (prevents stopping or resetting) examples: - false globalNetworking: $ref: '#/components/schemas/PodGlobalNetworking' runtime: description: Live utilization metrics. Null when the pod is not RUNNING. anyOf: - $ref: '#/components/schemas/PodRuntime' - type: 'null' createdAt: type: string format: date-time examples: - '2026-03-13T20:00:00Z' startedAt: type: - string - 'null' format: date-time examples: - '2026-03-13T20:00:00Z' ErrorResponse: type: object required: - title - status - detail properties: title: type: string description: Short human-readable summary examples: - Not Found status: type: integer description: HTTP status code examples: - 404 detail: type: string description: Human-readable explanation examples: - pod not found errors: type: array description: Individual request-validation failures. items: type: string examples: - - '$: additional properties ''bogus'' not allowed' PodAction: type: string description: State transition to trigger on a pod. enum: - start - stop - restart - terminate ContainerConfig: type: object description: > Reusable container configuration shared across templates, pods, and serverless endpoints. Adding a field here automatically propagates to all three resources. properties: image: type: string description: Docker image reference examples: - runpod/pytorch:2.8.0-py3.11-cuda12.8.1 args: type: string description: Arguments passed to the container entrypoint examples: - '' disk: type: integer minimum: 1 description: Container disk in GB (ephemeral, wiped on restart) examples: - 50 ports: type: array description: Exposed ports, formatted as port/protocol items: type: string examples: - - 8888/http - 22/tcp env: type: object additionalProperties: type: string description: Environment variables as key-value pairs examples: - JUPYTER_PASSWORD: hunter2 registry: type: - string - 'null' description: Container registry credential ID (for private images) examples: - null PodStatus: type: string description: | 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 enum: - PROVISIONING - STARTING - RUNNING - EXITED - ERROR - TERMINATED Mounts: type: object additionalProperties: false description: | 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. properties: persistent: $ref: '#/components/schemas/PersistentMount' network: type: array maxItems: 1 items: $ref: '#/components/schemas/NetworkMount' GpuConfig: type: object required: - id properties: id: type: string description: GPU type identifier examples: - NVIDIA GeForce RTX 4090 count: type: integer minimum: 1 default: 1 description: Number of GPUs examples: - 1 CpuConfig: allOf: - $ref: '#/components/schemas/BaseCpuConfig' - type: object required: - memory properties: memory: type: integer minimum: 1 description: Memory allocated to the pod in GB. examples: - 16 Cloud: type: string description: | Cloud tier. - `SECURE` — Runpod-owned datacenter hardware - `COMMUNITY` — community-hosted hardware enum: - SECURE - COMMUNITY PodGlobalNetworking: type: object required: - enabled properties: enabled: type: boolean description: >- Whether global networking is enabled, giving the pod a private IP reachable across data centers. Derived from whether the pod has an assigned global-network address. examples: - true ip: type: string description: The pod's assigned global-networking IP. Present only when enabled. examples: - 10.65.1.42 internalDns: type: string description: >- Internal DNS name (`.runpod.internal`), reachable from other globally-networked pods in the same account. Present only when enabled. examples: - gfj8b292vyg08g.runpod.internal PodRuntime: type: object description: Live utilization metrics for a running pod. properties: uptime: type: integer description: Seconds since the container started examples: - 3600 gpus: type: array items: $ref: '#/components/schemas/PodGpuUtilization' cpu: $ref: '#/components/schemas/Utilization' memory: $ref: '#/components/schemas/Utilization' ports: type: array items: $ref: '#/components/schemas/PodRuntimePort' PersistentMount: type: object required: - size - path additionalProperties: false description: | 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. properties: size: type: integer minimum: 10 description: >- Host-local persistent storage in GB. Upstream enforces a 10 GB floor. examples: - 20 path: type: string description: Mount path inside the container. May be changed via PATCH. examples: - /workspace NetworkMount: type: object required: - volumeId - path additionalProperties: false description: | Reference to a NetworkVolume. Custom paths are honored at runtime on both GPU and CPU pods. The underlying `volumeId` is immutable post-create; the mount `path` may be changed via PATCH. properties: volumeId: type: string description: ID of an existing NetworkVolume in the same data center as the pod. examples: - vol_xyz path: type: string description: >- Mount path inside the container. No default — must be specified explicitly. examples: - /runpod-volume BaseCpuConfig: type: object required: - id - vcpuCount properties: id: type: string description: CPU flavor identifier, as returned by GET /v2/catalog/cpus. examples: - cpu5c minLength: 1 vcpuCount: type: integer minimum: 2 description: >- Number of vCPUs. Must be valid for the selected CPU flavor and must be a power of two. examples: - 4 PodGpuUtilization: type: object description: Per-GPU utilization metrics. properties: util: type: integer examples: - 94 memoryUtil: type: integer examples: - 78 Utilization: type: object description: >- Single-value utilization percentage (0–100). Shared by `cpu` and `memory`. properties: util: type: integer examples: - 45 PodRuntimePort: type: object description: Live port mapping for a running pod. properties: private: type: integer examples: - 8888 public: type: - integer - 'null' examples: - 43210 type: type: string examples: - http ip: type: - string - 'null' examples: - 45.23.12.1 responses: BadRequestError: description: >- The request could not be processed because it is malformed or conflicts with request rules. content: application/problem+json: schema: $ref: '#/components/schemas/ErrorResponse' examples: badRequest: summary: Bad request value: title: Bad Request status: 400 detail: request could not be processed UnauthorizedError: description: >- Authentication failed because the bearer token is missing, malformed, expired, or invalid. content: application/problem+json: schema: $ref: '#/components/schemas/ErrorResponse' examples: missingBearerToken: summary: Missing bearer token value: title: Unauthorized status: 401 detail: missing bearer token ForbiddenError: description: >- The bearer token is valid, but it does not grant access to the requested resource or action. content: application/problem+json: schema: $ref: '#/components/schemas/ErrorResponse' examples: insufficientAccess: summary: Insufficient access value: title: Forbidden status: 403 detail: access denied NotFoundError: description: The requested resource was not found or is not accessible to the caller. content: application/problem+json: schema: $ref: '#/components/schemas/ErrorResponse' examples: notFound: summary: Resource not found value: title: Not Found status: 404 detail: resource not found UnprocessableEntityError: description: >- The request body or parameters were syntactically valid but failed validation. content: application/problem+json: schema: $ref: '#/components/schemas/ErrorResponse' examples: validationFailed: summary: Validation failed value: title: Unprocessable Entity status: 422 detail: Request validation failed. TooManyRequestsError: description: > 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. headers: Retry-After: description: Seconds to wait before retrying, per the exceeded window. schema: type: integer example: 12 RateLimit: description: > Live per-window state as a structured-field list — one member per window (`minute`, `hour`, `day`) with remaining count `r` and seconds-until-reset `t`. schema: type: string example: '"minute";r=0;t=12, "hour";r=2800;t=1812, "day";r=49500;t=45012' RateLimit-Policy: description: > Static quota policy as a structured-field list — one member per window with quota `q` and window length `w` (seconds). schema: type: string example: '"minute";q=60;w=60, "hour";q=3000;w=3600, "day";q=50000;w=86400' content: application/problem+json: schema: $ref: '#/components/schemas/ErrorResponse' examples: rateLimited: summary: Rate limit exceeded value: title: Too Many Requests status: 429 detail: rate limit exceeded for the minute window securitySchemes: bearerAuth: type: http scheme: bearer bearerFormat: Runpod API Key description: > Runpod API key authentication. Generate an API key in the Runpod console and send it in the `Authorization` header as `Bearer `. 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. ````