API reference · Pods
Get a pod: its state, configuration and how to connect
/v1/pods/{pod_id}- TypeScript
client.pods.get()- Python
client.pods.get()- CLI
hayonix pods show
Returns the pod with its current state, configuration, volumes and connection details (port URLs, SSH and private-network name). A terminated pod stays readable, without connection details.
Project API key (Authorization: Bearer sk_…), or a console session. Requires the workload:read 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" \
-H "Authorization: Bearer $API_KEY"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_
Response
200 Pod — The pod
objectstringrequiredAlways `pod`: the type of this object
One of
podidstringrequiredUnique ID (`pod_…`)
ID with prefix pod_
org_idstringrequiredOrganization it belongs to
ID with prefix org_
project_idstringrequiredProject it belongs to
ID with prefix prj_
namestringrequiredIts name
hostnamestringrequiredName in the project’s private network; does not change on rename
template_idstring | nullrequiredID of the template
ShowHide 5 fields of
statusstatestringrequiredqueued (waiting for capacity) · preempted (interruptible capacity reclaimed; waiting again) · pulling (downloading the image) · starting · running · restarting · stopping · stopped (compute released, volumes kept) · exited (the main process finished) · failed (see reason) · unreachable (its host stopped reporting) · terminating · terminated
One of
queuedpreemptedpullingstartingrunningrestartingstoppingstoppedexitedfailedunreachableterminatingterminatedreasonstring | nullrequiredMachine-readable cause of the state (why it waits, stopped or failed); null when there is none
messagestringrequiredOne sentence for people
sincestring (date-time)requiredWhen the pod entered this state
image_pullobject | nullrequiredImage download progress while the state is `pulling`; else null
ShowHide 6 fields of
image_pullimagestringrequiredContainer image reference
bytes_doneintegerrequiredBytes downloaded so far
bytes_totalintegerrequiredBytes to download in total (0 while unknown)
layers_doneintegerrequiredImage layers downloaded
layers_totalintegerrequiredImage layers in total
percentinteger | nullrequiredBytes downloaded, 0–100; null while the total is unknown
desired_statestringrequiredWhat was last asked for (create or start: `running`; stop: `stopped`; terminate: `terminated`). `status` shows where the pod actually is.
One of
runningstoppedterminatedShowHide 15 fields of
configimagestringrequiredContainer image reference
hardwareobjectrequiredSKU and number of GPUs the pod runs on
ShowHide 2 fields of
hardwareskustringrequiredHardware type code
gpu_countintegerrequiredNumber of GPUs
regionstringrequiredRegion code
pricing_classstringrequired`interruptible` costs less and may be stopped (preempted) when on-demand work needs the capacity; it then waits in the queue to run again. On-demand pods are never preempted.
One of
on_demandinterruptiblecontainer_disk_gbintegerrequiredWritable container disk in GB; reset whenever the container is recreated (stop, reconfigure)
volumeobject | nullrequiredThe pod’s own volume and where it is mounted; null for none
ShowHide 2 fields of
volumevolume_idstringrequiredID of the volume
mount_pathstringrequiredAbsolute path the volume is mounted at inside the container
network_volumesarray of objectrequiredNetwork volumes the pod mounts
ShowHide 3 fields of
network_volumesvolume_idstringrequiredID of the volume
mount_pathstringrequiredAbsolute path the volume is mounted at inside the container
read_onlybooleanrequiredMounted read-only
portsarray of objectrequiredExposed container ports
ShowHide 4 fields of
portsportintegerrequiredPort number the container listens on
protocolstringrequired`http`: served at the port’s HTTPS URL (WebSocket included). `tcp`: raw TCP, reachable through SSH port forwarding.
One of
httptcpvisibilitystringrequired`public`: anyone with the URL. `private`: no URL; SSH port forwarding and the project network only.
One of
publicprivatenamestringrequiredIts name
envarray of objectrequiredPlain environment variables
ShowHide 2 fields of
envnamestringrequiredIts name
valuestringrequiredValue of the variable
secret_envarray of objectrequiredEnvironment variables taken from project secrets (values are never shown)
ShowHide 2 fields of
secret_envnamestringrequiredIts name
secret_idstringrequiredID of the secret
commandarray of stringrequiredReplaces the image’s entrypoint when non-empty
argsarray of stringrequiredReplaces the image’s default arguments when non-empty
registry_credential_idstring | nullrequiredID of the registry credential
sshbooleanrequiredAllow SSH (and SFTP, port forwarding) with the project’s SSH keys
Models mounted read-only from the host’s model cache
ShowHide 1 field of
modelsreference_idstringrequiredThe model reference mounted
revisionintegerrequiredConfiguration revision (each change recreates the container)
hardwareobjectrequiredThe hardware the pod is configured for
ShowHide 4 fields of
hardwareskustringrequiredHardware type code
display_namestring | nullrequiredName to show people
gpu_countintegerrequiredNumber of GPUs
simulatedbooleanrequiredPlaced on a development host with simulated GPUs
Volumes the pod mounts: its own volume and network volumes
ShowHide 7 fields of
volumesidstringrequiredUnique ID
namestringrequiredIts name
kindstringrequired`pod`: this pod’s own volume. `network`: a network volume it mounts. (`cluster` volumes are never mounted by pods.)
One of
podnetworkclustersize_gbintegerrequiredSize in GB
pinned_to_hostbooleanrequiredThe volume lives on one host; pods using it run there
used_bytesinteger | nullrequiredSpace the volume uses on its host, as last measured; null until a host has measured it
usage_observed_atstring (date-time) | nullrequiredWhen `used_bytes` was measured
Present when reading one pod
ShowHide 3 fields of
connectportsarray of objectrequiredHow to reach each configured port
ShowHide 6 fields of
portsportintegerrequiredPort number the container listens on
namestringrequiredIts name
protocolstringrequired`http`: served at the port’s HTTPS URL (WebSocket included). `tcp`: raw TCP, reachable through SSH port forwarding.
One of
httptcpvisibilitystringrequired`public`: anyone with the URL. `private`: no URL; SSH port forwarding and the project network only.
One of
publicprivateurlstring | nullrequiredHTTPS URL (public HTTP ports)
forward_commandstring | nullrequiredSSH local-forward command reaching the port from your machine (when SSH is on)
sshobject | nullrequiredNull while SSH is off or the pod is not on a host
ShowHide 6 fields of
sshuserstringrequiredUser name to log in with (identifies the pod)
hoststringrequiredSSH host name
portintegerrequiredSSH TCP port
commandstringrequiredReady-to-run ssh command
known_hostsarray of stringrequiredLines for ~/.ssh/known_hosts pinning the host keys
sftp_commandstringrequiredReady-to-run sftp command
private_networkobjectrequiredHow other pods of the project reach this one
ShowHide 2 fields of
private_networkhostnamestringrequiredName this pod answers to in the project’s private network
scopestringrequiredOther pods of this project reach this one at `hostname` when they run on the same host (pods sharing a network volume always do). Pods of other projects cannot reach it.
One of
same_host
Container disk use of the running container against its size; null when nothing runs or the host has not measured it yet. It starts empty with every new container.
ShowHide 3 fields of
container_diskused_bytesintegerrequiredSpace used on the container disk
limit_bytesintegerrequiredThe container disk size enforced on the host (0: not enforced)
observed_atstring (date-time)requiredWhen it was measured
preemptionsobjectrequiredPreemptions of an interruptible pod
ShowHide 2 fields of
preemptionscountintegerrequiredTimes interruptible capacity was reclaimed from the pod
last_atstring (date-time) | nullrequiredTime last (ISO 8601, UTC)
created_atstring (date-time)requiredWhen it was created (ISO 8601, UTC)
updated_atstring (date-time)requiredWhen it last changed (ISO 8601, UTC)
terminated_atstring (date-time) | nullrequiredTime terminated (ISO 8601, UTC)
Example response
{
"object": "pod",
"id": "pod_01jc5zq4m8k3v6x9t2w7r0b1e4",
"org_id": "org_01jc5zq4m8k3v6x9t2w7r0b1e4",
"project_id": "prj_01jc5zq4m8k3v6x9t2w7r0b1e4",
"name": "string",
"hostname": "string",
"template_id": "string",
"status": {
"state": "queued",
"reason": "waiting_for_capacity",
"message": "string",
"since": "2026-01-01T00:00:00.000Z",
"image_pull": {
"image": "string",
"bytes_done": 1,
"bytes_total": 1,
"layers_done": 1,
"layers_total": 1,
"percent": 1
}
},
"desired_state": "running",
"config": {
"image": "string",
"hardware": {
"sku": "string",
"gpu_count": 1
},
"region": "string",
"pricing_class": "on_demand",
"container_disk_gb": 1,
"volume": {
"volume_id": "string",
"mount_path": "string"
},
"network_volumes": [
{
"volume_id": "string",
"mount_path": "string",
"read_only": true
}
],
"ports": [
{
"port": 1,
"protocol": "http",
"visibility": "public",
"name": "string"
}
],
"env": [
{
"name": "string",
"value": "string"
}
],
"secret_env": [
{
"name": "string",
"secret_id": "string"
}
],
"command": [
"string"
],
"args": [
"string"
],
"registry_credential_id": "string",
"ssh": true,
"models": [
{
"reference_id": "string"
}
]
},
"revision": 1,
"hardware": {
"sku": "string",
"display_name": "string",
"gpu_count": 1,
"simulated": true
},
"volumes": [
{
"id": "string",
"name": "string",
"kind": "pod",
"size_gb": 1,
"pinned_to_host": true,
"used_bytes": 1,
"usage_observed_at": "2026-01-01T00:00:00.000Z"
}
],
"connect": {
"ports": [
{
"port": 1,
"name": "string",
"protocol": "http",
"visibility": "public",
"url": "string",
"forward_command": "string"
}
],
"ssh": {
"user": "string",
"host": "string",
"port": 1,
"command": "string",
"known_hosts": [
"string"
],
"sftp_command": "string"
},
"private_network": {
"hostname": "string",
"scope": "same_host"
}
},
"container_disk": {
"used_bytes": 1,
"limit_bytes": 1,
"observed_at": "2026-01-01T00:00:00.000Z"
},
"preemptions": {
"count": 1,
"last_at": "2026-01-01T00:00:00.000Z"
},
"created_at": "2026-01-01T00:00:00.000Z",
"updated_at": "2026-01-01T00:00:00.000Z",
"terminated_at": "2026-01-01T00:00:00.000Z"
}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). |
429 | rate_limit_error rate_limited | Too many requests; retry after retry-after seconds. |