From 7e0cddbb8f2cc6169fae08f06b1ac9a4919eba17 Mon Sep 17 00:00:00 2001
From: "mintlify[bot]" <109931778+mintlify[bot]@users.noreply.github.com>
Date: Thu, 6 Aug 2026 13:10:29 +0000
Subject: [PATCH] docs: document runpodctl pod runtimeStatus and --ports
replacement
---
runpodctl/reference/runpodctl-pod.mdx | 100 +++++++++++++++++++++++++-
1 file changed, 99 insertions(+), 1 deletion(-)
diff --git a/runpodctl/reference/runpodctl-pod.mdx b/runpodctl/reference/runpodctl-pod.mdx
index 3ae1c05b4..26e72bf8f 100644
--- a/runpodctl/reference/runpodctl-pod.mdx
+++ b/runpodctl/reference/runpodctl-pod.mdx
@@ -44,6 +44,30 @@ runpodctl pod list --since 7d
runpodctl pod list --created-after 2025-01-15
```
+Example output (abbreviated):
+
+```json
+[
+ {
+ "id": "abc123xyz",
+ "name": "my-pod",
+ "desiredStatus": "RUNNING",
+ "runtimeStatus": "running",
+ "runtimeStatusReason": "",
+ "lastStatusChange": "Rented by User: ...",
+ "imageName": "runpod/pytorch:2.8.0-py3.11-cuda12.8.1-cudnn-devel-ubuntu22.04",
+ "gpuId": "NVIDIA GeForce RTX 4090",
+ "gpuCount": 1,
+ "costPerHr": 0.44,
+ "uptimeSeconds": 842
+ }
+]
+```
+
+Each Pod also includes a `runtimeStatus` and `runtimeStatusReason` field alongside `desiredStatus`, plus the backend's raw `lastStatusChange` note. See [Pod runtime status](#pod-runtime-status) for the full list of values.
+
+The `--status` flag filters on `desiredStatus` only (`RUNNING`, `EXITED`, and so on). It does not accept the lowercase `runtimeStatus` vocabulary.
+
#### List flags
@@ -78,6 +102,28 @@ Get detailed information about a specific Pod, including SSH connection info:
runpodctl pod get
```
+Example output (abbreviated):
+
+```json
+{
+ "id": "abc123xyz",
+ "name": "my-pod",
+ "desiredStatus": "RUNNING",
+ "runtimeStatus": "running",
+ "runtimeStatusReason": "",
+ "lastStatusChange": "Rented by User: ...",
+ "imageName": "runpod/pytorch:2.8.0-py3.11-cuda12.8.1-cudnn-devel-ubuntu22.04",
+ "uptimeSeconds": 842,
+ "ssh": {
+ "ssh_command": "ssh root@... -p 12345 -i ~/.ssh/id_ed25519"
+ }
+}
+```
+
+`desiredStatus` reports what you asked the platform to do. `runtimeStatus` reports what the Pod is actually doing, derived from live runtime telemetry. Use `runtimeStatus` to tell an initializing Pod (image still pulling) apart from one that is serving traffic. See [Pod runtime status](#pod-runtime-status) for the full list of values.
+
+`uptimeSeconds` is the container's uptime and is omitted whenever no container is reporting.
+
### Create a Pod
Create a new Pod from a template:
@@ -259,7 +305,7 @@ New volume mount path.
-New comma-separated list of ports.
+New comma-separated list of ports. This flag **replaces** the Pod's entire port list rather than appending to it, so include every port you want to keep. Changing the port list bumps the Pod's version and may restart the container, so processes and container-local state outside the volume may not survive the update.
@@ -274,6 +320,58 @@ Delete a Pod:
runpodctl pod delete
```
+## Pod runtime status
+
+`pod get` and `pod list` report a derived `runtimeStatus` (and an optional `runtimeStatusReason` token) alongside the platform's `desiredStatus`. Use `runtimeStatus` when you need to know what the Pod is actually doing; a Pod whose 20 GB image is still downloading and one that has been serving traffic for an hour both show `desiredStatus: RUNNING`, but only the second shows `runtimeStatus: running`.
+
+Branch scripts on the token values below, not on the free-text `lastStatusChange`.
+
+### `runtimeStatus` values
+
+
+`desiredStatus` is `RUNNING` and the platform is reporting runtime telemetry. The container is up. Does not imply any port is reachable.
+
+
+
+`desiredStatus` is `RUNNING` but no runtime telemetry is being reported yet. The Pod is placed on a machine but the container is not up (image pull, container create, or boot). Keep polling.
+
+
+
+`desiredStatus` is `EXITED` and the last transition was not a termination. The container is gone but the disk is kept; `pod start` will bring it back.
+
+
+
+The Pod is being destroyed. Terminated Pods drop out of `pod list` shortly after, so this is a narrow window.
+
+
+
+The runtime status could not be derived, either because the runtime telemetry lookup failed or because `desiredStatus` is a value the platform does not surface in practice. Read `desiredStatus`, which is in the same output.
+
+
+### `runtimeStatusReason` tokens
+
+
+Paired with `initializing`. No container is being reported for a Pod that should be running.
+
+
+
+You stopped or terminated the Pod.
+
+
+
+Runpod stopped or terminated the Pod. The platform does not record a machine-readable cause; in practice this is insufficient credit, a fatal image-pull failure, or host action.
+
+
+
+A Spot or Community Cloud Pod lost its machine to a higher bid. Retry elsewhere or at on-demand pricing.
+
+
+
+Paired with `unknown`. The runtime telemetry lookup could not be made, so `running` and `initializing` cannot be told apart.
+
+
+The token is a lossy read of the backend's free-text `lastStatusChange`. A phrasing the CLI does not recognize leaves `runtimeStatusReason` absent rather than wrong; the raw text is still available in the `lastStatusChange` field on the same output.
+
## Pod URLs
Access exposed ports on your Pod using the following URL pattern: