Skip to content
Hayonix

API reference · Clusters

List clusters in the project, newest first (deleted ones only when asked for)

GET/v1/clusters
API keycluster:readProjectPaginated
TypeScript
client.clusters.list()
Python
client.clusters.list()
CLI
hayonix clusters list

Returns clusters with their state and members; pass include_deleted=true to list deleted ones as well.

Project API key (Authorization: Bearer sk_…), or a console session. Requires the cluster: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/clusters" \
  -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.

Query parameters

  • limitinteger

    1–200, default 50

    1–200

  • cursorstring

    `next_cursor` of the previous page

    up to 200 characters

  • include_deletedboolean | string

    Also list deleted clusters (default false)

Response

200 a page of results — A page of clusters

  • dataarray of Clusterrequired

    The items of this page.

    Show 26 fields of data
    • objectstringrequired

      Always `cluster`: the type of this object

      One ofcluster

    • idstringrequired

      Unique ID (`clu_…`)

      ID with prefix clu_

    • org_idstringrequired

      Organization it belongs to

      ID with prefix org_

    • project_idstringrequired

      Project it belongs to

      ID with prefix prj_

    • namestringrequired

      Its name

    • statestringrequired

      provisioning | running | degraded (a member failed or lost its host; the others keep running and billing) | stopped (billing or host maintenance; only deletion remains) | deleting | deleted

      One ofprovisioningrunningdegradedstoppeddeletingdeleted

    • state_reasonstring | nullrequired

      Why it is degraded, stopped or deleted: member_failed, host_lost, shared_volume_unavailable (the host holding the shared volume stopped answering: I/O on it fails on the other members after about two minutes), billing, host_maintenance, requested

    • member_countintegerrequired

      Number of members

    • hardwareobjectrequired

      What each member runs on

      Show 3 fields of hardware
      • skustringrequired

        Hardware SKU of every member

      • display_namestring | nullrequired

        The SKU’s display name

      • gpus_per_memberintegerrequired

        GPUs per member

    • regionstring | nullrequired

      Region code

    • imagestringrequired

      Container image every member runs

    • template_idstring | nullrequired

      Template it was created from

    • Environment variables of every member (besides the platform’s own)

      Show 2 fields of env
      • namestringrequired

        Variable name (the CLUSTER_RUNTIME_ prefix is reserved)

      • valuestringrequired

        Its value

    • Variables taken from project secrets

      Show 2 fields of secret_env
      • namestringrequired

        Variable name

      • secret_idstringrequired

        A secret of this project; its value is set when members start

        ID with prefix sec_

    • commandarray of stringrequired

      Entrypoint override

    • argsarray of stringrequired

      Command override

    • container_disk_gbintegerrequired

      Writable container disk per member

    • one_member_per_hostbooleanrequired

      Every member was placed on a host of its own

    • private_networkobjectrequired

      How members reach each other

      Show 3 fields of private_network
      • subnetstringrequired

        Its private network, fixed for the cluster’s life

      • env_prefixstringrequired

        Prefix of the variables the platform sets in every member

      • launcherstringrequired

        Path, inside every member, of the launcher that starts processes on other members (ssh-compatible arguments)

    • shared_volumeobject | nullrequired

      The shared volume, if the cluster has one

      Show 4 fields of shared_volume
      • volume_idstringrequired

        ID of the volume

        ID with prefix vol_

      • size_gbintegerrequired

        Size in GB

      • mount_pathstringrequired

        Where every member mounts it

      • served_by_rankintegerrequired

        The member whose host holds the data (the head); if that host is lost, the volume is unavailable

    • membersarray of ClusterMemberrequired

      Every member, by rank

      Show 10 fields of members
      • objectstringrequired

        Always `cluster_member`: the type of this object

        One ofcluster_member

      • rankintegerrequired

        Its rank: 0 is the head

      • hostnamestringrequired

        Its name, resolvable on every member

      • addressstringrequired

        Its fixed private address on the cluster’s network

      • statestringrequired

        starting | running | failed (its container exited or could not start; nothing restarts it) | host_lost | stopped | deleted

        One ofstartingrunningfailedhost_loststoppeddeleted

      • state_reasonstring | nullrequired

        Machine-readable cause the host reported, when there is one

      • host_idstringrequired

        The host it was placed on (opaque; members with the same value share a host)

      • simulated_gpusbooleanrequired

        Its host advertises simulated GPUs (development only)

      • started_atstring (date-time) | nullrequired

        When its current run started (null when not running)

      • sshClusterMemberSshrequired

        How to open a shell on it through the SSH gateway (present when reading one cluster)

        Show 5 fields of ssh
        • userstringrequired

          SSH user name (the member’s own identity)

        • hoststringrequired

          SSH gateway host

        • portintegerrequired

          SSH gateway port

        • commandstringrequired

          Ready-to-run ssh command (uses one of the project’s SSH keys)

        • known_hostsarray of stringrequired

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

    • priceobjectrequired

      What it costs at today’s prices: compute while members run, storage while the cluster exists

      Show 3 fields of price
      • per_hourstring | nullrequired

        Compute of every member per hour at today’s prices, nano-USD (null if the SKU is not priced)

        pattern ^-?[0-9]+$

      • member_per_hourstring | nullrequired

        One member’s compute per hour, nano-USD

        pattern ^-?[0-9]+$

      • shared_volume_per_hourstringrequired

        The shared volume’s storage per hour, nano-USD (rounded down; billed per GB-second while the cluster exists, running or not)

        pattern ^-?[0-9]+$

    • created_atstring (date-time)required

      When it was created (ISO 8601, UTC)

    • updated_atstring (date-time)required

      When it last changed (ISO 8601, UTC)

    • stopped_atstring (date-time) | nullrequired

      When its compute was stopped, if it was

    • deleted_atstring (date-time) | nullrequired

      When it was deleted, if it was

  • next_cursorstring | nullrequired

    Pass as `cursor` for the next page; null on the last page.

Example response
Example response
{
  "data": [
    {
      "object": "cluster",
      "id": "clu_01jc5zq4m8k3v6x9t2w7r0b1e4",
      "org_id": "org_01jc5zq4m8k3v6x9t2w7r0b1e4",
      "project_id": "prj_01jc5zq4m8k3v6x9t2w7r0b1e4",
      "name": "string",
      "state": "provisioning",
      "state_reason": "string",
      "member_count": 1,
      "hardware": {
        "sku": "string",
        "display_name": "string",
        "gpus_per_member": 1
      },
      "region": "string",
      "image": "string",
      "template_id": "string",
      "env": [
        {
          "name": "string",
          "value": "string"
        }
      ],
      "secret_env": [
        {
          "name": "string",
          "secret_id": "sec_01jc5zq4m8k3v6x9t2w7r0b1e4"
        }
      ],
      "command": [
        "string"
      ],
      "args": [
        "string"
      ],
      "container_disk_gb": 1,
      "one_member_per_host": true,
      "private_network": {
        "subnet": "10.224.5.0/24",
        "env_prefix": "string",
        "launcher": "string"
      },
      "shared_volume": {
        "volume_id": "vol_01jc5zq4m8k3v6x9t2w7r0b1e4",
        "size_gb": 1,
        "mount_path": "string",
        "served_by_rank": 1
      },
      "members": [
        {
          "object": "cluster_member",
          "rank": 1,
          "hostname": "member-0",
          "address": "string",
          "state": "starting",
          "state_reason": "string",
          "host_id": "string",
          "simulated_gpus": true,
          "started_at": "2026-01-01T00:00:00.000Z",
          "ssh": {
            "user": "string",
            "host": "string",
            "port": 1,
            "command": "string",
            "known_hosts": [
              null
            ]
          }
        }
      ],
      "price": {
        "per_hour": "1500000000",
        "member_per_hour": "1500000000",
        "shared_volume_per_hour": "1500000000"
      },
      "created_at": "2026-01-01T00:00:00.000Z",
      "updated_at": "2026-01-01T00:00:00.000Z",
      "stopped_at": "2026-01-01T00:00:00.000Z",
      "deleted_at": "2026-01-01T00:00:00.000Z"
    }
  ],
  "next_cursor": "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.
429rate_limit_error rate_limitedToo many requests; retry after retry-after seconds.