From 88cea04fb7e63a4dd75696a0b44fd6f64cf04496 Mon Sep 17 00:00:00 2001 From: "promptless[bot]" Date: Tue, 4 Aug 2026 20:14:06 +0000 Subject: [PATCH 1/2] Document serverless run, status, and health CLI commands Add reference sections for the new runpodctl serverless invoke-time subcommands (run, status, health) introduced in runpod/runpodctl#316 (CON-688), including input/payload rules, wait behavior, exit codes, and the timeout/job_failed error semantics. --- runpodctl/reference/runpodctl-serverless.mdx | 90 ++++++++++++++++++++ 1 file changed, 90 insertions(+) diff --git a/runpodctl/reference/runpodctl-serverless.mdx b/runpodctl/reference/runpodctl-serverless.mdx index a80cd6f13..966ea3c4b 100644 --- a/runpodctl/reference/runpodctl-serverless.mdx +++ b/runpodctl/reference/runpodctl-serverless.mdx @@ -232,6 +232,96 @@ Delete an endpoint: runpodctl serverless delete ``` +### Run a job + +Submit a job to an endpoint, poll until the job reaches a terminal status (such as `COMPLETED`, `FAILED`, `CANCELLED`, or `TIMED_OUT`), then print the job's response: + +```bash +# Submit a job with an inline JSON payload and wait for it to finish +runpodctl serverless run --input '{"prompt": "hello"}' + +# Read the payload from a file +runpodctl serverless run --input-file ./payload.json + +# Read the payload from stdin +echo '{"prompt": "hello"}' | runpodctl serverless run --input - + +# Submit without waiting; print the queued job and return +runpodctl serverless run --input '{"prompt": "hello"}' --no-wait + +# Wait up to 90 seconds for a terminal status +runpodctl serverless run --input '{"prompt": "hello"}' --wait 90s +``` + +`run`, `status`, and `health` call the endpoint's `/run`, `/status`, and `/health` URLs (listed under [Serverless URLs](#serverless-urls) below). + +You must provide one of `--input` or `--input-file`, and they're mutually exclusive. The payload must be a JSON object. `runpodctl` rejects arrays, scalars, and `null` locally as a usage error before it sends any request. + +`runpodctl` automatically nests the payload under an `input` key, so provide only the handler input, not a wrapper. If you include your own top-level `input` key, `runpodctl` warns you about the likely double-wrapping but still submits the request, so remove the extra key to avoid nesting your input twice. + +The job's response always prints to stdout, including a failed job's error and the last-known response when the wait budget runs out. Progress notes and errors go to stderr. + +| Exit code | Meaning | +|-----------|---------| +| `0` | The job completed successfully, or (with `--no-wait` or `--wait 0`) the job was submitted successfully and is still queued or running. | +| `1` | The request failed, the wait budget ran out (a `timeout` error), or the job ended in a `FAILED`, `CANCELLED`, or `TIMED_OUT` state (a `job_failed` error). | + +The `timeout` error means `runpodctl` stopped waiting, either because the `--wait` budget ran out while the job was still running server-side, or because a single API call exceeded its per-call timeout. If the budget ran out while the job is still running, use `runpodctl serverless status` to keep polling rather than resubmitting the job. The `job_failed` error means the job reached a terminal status other than completed. Because all three failures share exit code `1`, use the error code printed in the stderr error object (`timeout` or `job_failed`) to tell a wait or job failure apart from a request failure. + +#### Run flags + + +JSON payload for the handler. Use `-` to read the payload from stdin. Mutually exclusive with `--input-file`. + + + +Read the JSON payload from a file. Use `-` to read from stdin. Mutually exclusive with `--input`. + + + +How long to wait for a terminal job status (for example, `90s` or `10m`). Set to `0` to submit without waiting. + + + +Submit the job and print its ID without waiting. Equivalent to `--wait 0`. + + +### Check job status + +Get the current status and payload of a previously submitted job: + +```bash +# Check the status once +runpodctl serverless status + +# Keep polling for up to 5 minutes until the job is terminal +runpodctl serverless status --wait 5m +``` + +This command takes exactly two arguments: the endpoint ID and the job ID. By default it checks once and prints the current job response. This is how you resume watching a job started with `run --no-wait`, or one whose `--wait` budget expired. + +#### Check flags + + +Keep polling until the job reaches a terminal status, up to this long. `0` checks once and returns. + + +### Check endpoint health + +Print the health check response for an endpoint: + +```bash +runpodctl serverless health +``` + +This command takes exactly one argument: the endpoint ID. Use it to check whether an endpoint's workers are available before assuming a problem with your own request. + + + +Health can still return a response for a recently deleted endpoint because of invoke-side caching, so it is not a reliable existence check. Use `runpodctl serverless get` for that. + + + ## Serverless URLs Access your Serverless endpoint using these URL patterns: From 6848519070e9b856640a42b792e651b1fe8a9c68 Mon Sep 17 00:00:00 2001 From: "promptless[bot]" Date: Thu, 6 Aug 2026 21:43:11 +0000 Subject: [PATCH 2/2] Reflect merged serverless run validations (10 MiB limit, --no-wait/--wait conflict) --- runpodctl/reference/runpodctl-serverless.mdx | 4 ++-- 1 file changed, 2 insertions(+), 2 deletions(-) diff --git a/runpodctl/reference/runpodctl-serverless.mdx b/runpodctl/reference/runpodctl-serverless.mdx index 966ea3c4b..f6305dd81 100644 --- a/runpodctl/reference/runpodctl-serverless.mdx +++ b/runpodctl/reference/runpodctl-serverless.mdx @@ -255,7 +255,7 @@ runpodctl serverless run --input '{"prompt": "hello"}' --wait 90s `run`, `status`, and `health` call the endpoint's `/run`, `/status`, and `/health` URLs (listed under [Serverless URLs](#serverless-urls) below). -You must provide one of `--input` or `--input-file`, and they're mutually exclusive. The payload must be a JSON object. `runpodctl` rejects arrays, scalars, and `null` locally as a usage error before it sends any request. +You must provide one of `--input` or `--input-file`, and they're mutually exclusive. The payload must be a JSON object. `runpodctl` rejects arrays, scalars, `null`, and any payload whose compacted `{"input": ...}` request body exceeds 10 MiB locally as a usage error, before it sends any request. `runpodctl` automatically nests the payload under an `input` key, so provide only the handler input, not a wrapper. If you include your own top-level `input` key, `runpodctl` warns you about the likely double-wrapping but still submits the request, so remove the extra key to avoid nesting your input twice. @@ -283,7 +283,7 @@ How long to wait for a terminal job status (for example, `90s` or `10m`). Set to -Submit the job and print its ID without waiting. Equivalent to `--wait 0`. +Submit the job and print its ID without waiting. Equivalent to `--wait 0`. Cannot be combined with an explicit `--wait`; passing both is rejected locally as a usage error. ### Check job status