Skip to content
Hayonix

API reference · Pods

Run a command in the pod and wait for it (bounded time and output)

POST/v1/pods/{pod_id}/exec
API keyworkload:updateProject
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

Headers
HeaderRequiredDescription
AuthorizationyesBearer and your API key. The key implies its project.
X-Project-Idsession onlyThe project to act in, for console sessions. Requests with an API key leave it out.

Path parameters

  • pod_idstringrequired

    ID of the pod

    ID with prefix pod_

Body

JSON (application/json): PodExecRequest.

  • commandarray of stringrequired

    Program and its arguments, run without a shell (use `["sh", "-c", "…"]` for shell syntax)

    1–64 items

  • working_dirstring

    Directory to run in (default: the image’s working directory)

    up to 1024 characters

  • timeout_secondsinteger

    Seconds 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

  • objectstringrequired

    Always `exec_result`: the type of this object

    One ofexec_result

  • exit_codeinteger | nullrequired

    Null when it timed out or could not start

  • stdoutstringrequired

    UTF-8 (invalid sequences replaced)

  • stderrstringrequired

    UTF-8 (invalid sequences replaced)

  • timed_outbooleanrequired

    The command did not finish within `timeout_seconds`

  • truncatedbooleanrequired

    Output beyond 1048576 bytes per stream was discarded

  • duration_msintegerrequired

    How long the command ran, in milliseconds

  • errorstring | nullrequired

    Why the command could not be run; null when it ran (finished or timed out)

Example response
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:

Errors
StatusTypeWhen
400invalid_request_errorA parameter or body field is missing or not allowed; param names it.
401authentication_errorThe key or session is missing, revoked or expired.
403permission_errorThe credential lacks the permission this needs, or the organization is suspended.
404not_found_errorNo such resource in this project (an ID from another project is answered the same way).
409conflict_errorThe resource's current state does not allow this.
429rate_limit_error rate_limitedToo many requests; retry after retry-after seconds.