Skip to content
Hayonix

API reference · Schema

Cluster

  • 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

Example
{
  "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": [
          "string"
        ]
      }
    }
  ],
  "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"
}

Used by