Skip to content
Hayonix

API reference · Pods

Stop a pod: compute released and no longer billed; volumes kept (and billed)

POST/v1/pods/{pod_id}/stop
API keyworkload:updateProject
TypeScript
client.pods.stop()
Python
client.pods.stop()
CLI
hayonix pods stop

Stops the container, then releases the pod’s GPUs, CPU and memory; compute billing stops. Only volume data is kept. Calling it on a pod that is already stopped changes nothing.

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 -X POST "$API_BASE_URL/pods/pod_01jc5zq4m8k3v6x9t2w7r0b1e4/stop" \
  -H "Authorization: Bearer $API_KEY"

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_

Response

200 Pod — The pod

  • objectstringrequired

    Always `pod`: the type of this object

    One ofpod

  • idstringrequired

    Unique ID (`pod_…`)

    ID with prefix pod_

  • org_idstringrequired

    Organization it belongs to

    ID with prefix org_

  • project_idstringrequired

    Project it belongs to

    ID with prefix prj_

  • namestringrequired

    Its name

  • hostnamestringrequired

    Name in the project’s private network; does not change on rename

  • template_idstring | nullrequired

    ID of the template

  • statusPodStatusrequired
    Show 5 fields of status
    • statestringrequired

      queued (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 ofqueuedpreemptedpullingstartingrunningrestartingstoppingstoppedexitedfailedunreachableterminatingterminated

    • reasonstring | nullrequired

      Machine-readable cause of the state (why it waits, stopped or failed); null when there is none

    • messagestringrequired

      One sentence for people

    • sincestring (date-time)required

      When the pod entered this state

    • image_pullobject | nullrequired

      Image download progress while the state is `pulling`; else null

      Show 6 fields of image_pull
      • imagestringrequired

        Container image reference

      • bytes_doneintegerrequired

        Bytes downloaded so far

      • bytes_totalintegerrequired

        Bytes to download in total (0 while unknown)

      • layers_doneintegerrequired

        Image layers downloaded

      • layers_totalintegerrequired

        Image layers in total

      • percentinteger | nullrequired

        Bytes downloaded, 0–100; null while the total is unknown

  • desired_statestringrequired

    What was last asked for (create or start: `running`; stop: `stopped`; terminate: `terminated`). `status` shows where the pod actually is.

    One ofrunningstoppedterminated

  • configPodConfigrequired
    Show 15 fields of config
    • imagestringrequired

      Container image reference

    • hardwareobjectrequired

      SKU and number of GPUs the pod runs on

      Show 2 fields of hardware
      • skustringrequired

        Hardware type code

      • gpu_countintegerrequired

        Number of GPUs

    • regionstringrequired

      Region 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 ofon_demandinterruptible

    • container_disk_gbintegerrequired

      Writable container disk in GB; reset whenever the container is recreated (stop, reconfigure)

    • volumeobject | nullrequired

      The pod’s own volume and where it is mounted; null for none

      Show 2 fields of volume
      • volume_idstringrequired

        ID of the volume

      • mount_pathstringrequired

        Absolute path the volume is mounted at inside the container

    • network_volumesarray of objectrequired

      Network volumes the pod mounts

      Show 3 fields of network_volumes
      • volume_idstringrequired

        ID of the volume

      • mount_pathstringrequired

        Absolute path the volume is mounted at inside the container

      • read_onlybooleanrequired

        Mounted read-only

    • portsarray of objectrequired

      Exposed container ports

      Show 4 fields of ports
      • portintegerrequired

        Port 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 ofhttptcp

      • visibilitystringrequired

        `public`: anyone with the URL. `private`: no URL; SSH port forwarding and the project network only.

        One ofpublicprivate

      • namestringrequired

        Its name

    • envarray of objectrequired

      Plain environment variables

      Show 2 fields of env
      • namestringrequired

        Its name

      • valuestringrequired

        Value of the variable

    • secret_envarray of objectrequired

      Environment variables taken from project secrets (values are never shown)

      Show 2 fields of secret_env
      • namestringrequired

        Its name

      • secret_idstringrequired

        ID of the secret

    • commandarray of stringrequired

      Replaces the image’s entrypoint when non-empty

    • argsarray of stringrequired

      Replaces the image’s default arguments when non-empty

    • registry_credential_idstring | nullrequired

      ID of the registry credential

    • sshbooleanrequired

      Allow SSH (and SFTP, port forwarding) with the project’s SSH keys

    • Models mounted read-only from the host’s model cache

      Show 1 field of models
      • reference_idstringrequired

        The model reference mounted

  • revisionintegerrequired

    Configuration revision (each change recreates the container)

  • hardwareobjectrequired

    The hardware the pod is configured for

    Show 4 fields of hardware
    • skustringrequired

      Hardware type code

    • display_namestring | nullrequired

      Name to show people

    • gpu_countintegerrequired

      Number of GPUs

    • simulatedbooleanrequired

      Placed on a development host with simulated GPUs

  • Volumes the pod mounts: its own volume and network volumes

    Show 7 fields of volumes
    • idstringrequired

      Unique ID

    • namestringrequired

      Its name

    • kindstringrequired

      `pod`: this pod’s own volume. `network`: a network volume it mounts. (`cluster` volumes are never mounted by pods.)

      One ofpodnetworkcluster

    • size_gbintegerrequired

      Size in GB

    • pinned_to_hostbooleanrequired

      The volume lives on one host; pods using it run there

    • used_bytesinteger | nullrequired

      Space the volume uses on its host, as last measured; null until a host has measured it

    • usage_observed_atstring (date-time) | nullrequired

      When `used_bytes` was measured

  • connectPodConnectrequired

    Present when reading one pod

    Show 3 fields of connect
    • portsarray of objectrequired

      How to reach each configured port

      Show 6 fields of ports
      • portintegerrequired

        Port number the container listens on

      • namestringrequired

        Its name

      • protocolstringrequired

        `http`: served at the port’s HTTPS URL (WebSocket included). `tcp`: raw TCP, reachable through SSH port forwarding.

        One ofhttptcp

      • visibilitystringrequired

        `public`: anyone with the URL. `private`: no URL; SSH port forwarding and the project network only.

        One ofpublicprivate

      • urlstring | nullrequired

        HTTPS URL (public HTTP ports)

      • forward_commandstring | nullrequired

        SSH local-forward command reaching the port from your machine (when SSH is on)

    • sshobject | nullrequired

      Null while SSH is off or the pod is not on a host

      Show 6 fields of ssh
      • userstringrequired

        User name to log in with (identifies the pod)

      • hoststringrequired

        SSH host name

      • portintegerrequired

        SSH TCP port

      • commandstringrequired

        Ready-to-run ssh command

      • known_hostsarray of stringrequired

        Lines for ~/.ssh/known_hosts pinning the host keys

      • sftp_commandstringrequired

        Ready-to-run sftp command

    • private_networkobjectrequired

      How other pods of the project reach this one

      Show 2 fields of private_network
      • hostnamestringrequired

        Name this pod answers to in the project’s private network

      • scopestringrequired

        Other 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 ofsame_host

  • container_diskPodContainerDiskUsagerequired

    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.

    Show 3 fields of container_disk
    • used_bytesintegerrequired

      Space used on the container disk

    • limit_bytesintegerrequired

      The container disk size enforced on the host (0: not enforced)

    • observed_atstring (date-time)required

      When it was measured

  • preemptionsobjectrequired

    Preemptions of an interruptible pod

    Show 2 fields of preemptions
    • countintegerrequired

      Times interruptible capacity was reclaimed from the pod

    • last_atstring (date-time) | nullrequired

      Time last (ISO 8601, UTC)

  • created_atstring (date-time)required

    When it was created (ISO 8601, UTC)

  • updated_atstring (date-time)required

    When it last changed (ISO 8601, UTC)

  • terminated_atstring (date-time) | nullrequired

    Time terminated (ISO 8601, UTC)

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

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.