API reference · Pods
Run a command in the pod and wait for it (bounded time and output)
/v1/pods/{pod_id}/exec- TypeScript
client.pods.exec()- Python
client.pods.exec()- CLI
hayonix pods exec
Runs a command in the running container, without a terminal or input, and returns its exit code and output once it finishes or times out. Each output stream is capped and the excess discarded. Refused unless the pod is running.
Project API key (Authorization: Bearer sk_…), or a console session. Requires the workload:update permission (a key's scope, or a role that includes it).
Examples
The samples read API_KEY and API_BASE_URL from the environment (see Setup). Values are examples.
curl -sS "$API_BASE_URL/pods/pod_01jc5zq4m8k3v6x9t2w7r0b1e4/exec" \
-H "Authorization: Bearer $API_KEY" \
-H "Content-Type: application/json" \
-d '{
"command": [
"uname",
"-a"
],
"timeout_seconds": 10
}'Request
| Header | Required | Description |
|---|---|---|
Authorization | yes | Bearer and your API key. The key implies its project. |
X-Project-Id | session only | The project to act in, for console sessions. Requests with an API key leave it out. |
Path parameters
pod_idstringrequiredID of the pod
ID with prefix pod_
Body
JSON (application/json): PodExecRequest.
commandarray of stringrequiredProgram and its arguments, run without a shell (use `["sh", "-c", "…"]` for shell syntax)
1–64 items
working_dirstringDirectory to run in (default: the image’s working directory)
up to 1024 characters
timeout_secondsintegerSeconds to wait for the command (default 30); after that the call returns with `timed_out` true
1–120 · default 30
Response
200 PodExecResult — Exit code and output
objectstringrequiredAlways `exec_result`: the type of this object
One of
exec_resultexit_codeinteger | nullrequiredNull when it timed out or could not start
stdoutstringrequiredUTF-8 (invalid sequences replaced)
stderrstringrequiredUTF-8 (invalid sequences replaced)
timed_outbooleanrequiredThe command did not finish within `timeout_seconds`
truncatedbooleanrequiredOutput beyond 1048576 bytes per stream was discarded
duration_msintegerrequiredHow long the command ran, in milliseconds
errorstring | nullrequiredWhy the command could not be run; null when it ran (finished or timed out)
Example response
{
"object": "exec_result",
"exit_code": 1,
"stdout": "string",
"stderr": "string",
"timed_out": true,
"truncated": true,
"duration_ms": 1,
"error": "string"
}Errors
Errors use the standard envelope. What this operation can answer:
| Status | Type | When |
|---|---|---|
400 | invalid_request_error | A parameter or body field is missing or not allowed; param names it. |
401 | authentication_error | The key or session is missing, revoked or expired. |
403 | permission_error | The credential lacks the permission this needs, or the organization is suspended. |
404 | not_found_error | No such resource in this project (an ID from another project is answered the same way). |
409 | conflict_error | The resource's current state does not allow this. |
429 | rate_limit_error rate_limited | Too many requests; retry after retry-after seconds. |