Skip to content
Hayonix

API reference · Volumes

List live volumes in the project

GET/v1/volumes
API keyvolume:readProjectPaginated
TypeScript
client.volumes.list()
Python
client.volumes.list()
CLI
hayonix volumes list

Pod volumes and network volumes of the project that have not been deleted, newest first, each with the pods that mount it.

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

  • kindstring

    Only pod volumes or only network volumes (default: both)

    One ofpodnetworkcluster

Response

200 a page of results — A page of volumes, newest first

  • dataarray of Volumerequired

    The items of this page.

    Show 18 fields of data
    • objectstringrequired

      Always `volume`: the type of this object

      One ofvolume

    • idstringrequired

      Unique ID (`vol_…`)

      ID with prefix vol_

    • org_idstringrequired

      Organization it belongs to

      ID with prefix org_

    • project_idstringrequired

      Project it belongs to

      ID with prefix prj_

    • namestringrequired

      Its name

    • kindstringrequired

      `pod`: one pod’s own volume (exclusive). `network`: standalone, mountable by several pods at once. `cluster`: a cluster’s shared volume (deleted with the cluster).

      One ofpodnetworkcluster

    • size_gbintegerrequired

      Size in GB; storage is billed on this size

    • regionstringrequired

      Region code

    • statusstringrequired

      `creating`: being set up. `ready`: usable. `deleting`: deleted and billing stopped; its host is removing the data. `deleted`: the data is gone.

      One ofcreatingreadydeletingdeleted

    • pinned_to_hostbooleanrequired

      Volumes live on one host until shared storage exists. Once a pod has mounted it, the volume is pinned to that host, and every pod that mounts it (now or later) runs on that host — waiting for capacity there if it is full.

    • owner_pod_idstring | nullrequired

      ID of the owner pod

    • usageobject | nullrequired

      Space used against the size, as last measured by the host it lives on (while a pod or worker mounts it); null until then

      Show 3 fields of usage
      • used_bytesintegerrequired

        Space used on its host

      • size_bytesintegerrequired

        The size, enforced on the host: writes beyond it fail

      • observed_atstring (date-time)required

        When it was measured

    • attachmentsarray of objectrequired

      Pods whose configuration mounts the volume

      Show 3 fields of attachments
      • pod_idstringrequired

        ID of the pod

      • mount_pathstringrequired

        Absolute path the volume is mounted at inside the container

      • read_onlybooleanrequired

        Mounted read-only in that pod

    • endpoint_attachmentsarray of objectrequired

      Serverless endpoints whose current release mounts the volume, or that still have a worker mounting it. While any is listed the volume cannot be deleted.

      Show 3 fields of endpoint_attachments
      • endpoint_idstringrequired

        The serverless endpoint

      • mount_pathstringrequired

        Where its workers see the volume

      • read_onlybooleanrequired

        Mounted read-only in its workers

    • billingobjectrequired

      How the volume’s storage is charged

      Show 3 fields of billing
      • meterstringrequired

        Unit of use: GB of size per second, from creation to deletion

        One ofstorage_gb_second

      • price_keystringrequired

        Price list entry the storage is charged at: `pod_volume` or `network_volume`

      • billed_untilstring (date-time) | nullrequired

        Storage is billed from creation to deletion, attached or not

    • created_atstring (date-time)required

      When it was created (ISO 8601, UTC)

    • updated_atstring (date-time)required

      When it last changed (ISO 8601, UTC)

    • deleted_atstring (date-time) | nullrequired

      When it was deleted (null while it exists) (ISO 8601, UTC)

  • next_cursorstring | nullrequired

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

Example response
Example response
{
  "data": [
    {
      "object": "volume",
      "id": "vol_01jc5zq4m8k3v6x9t2w7r0b1e4",
      "org_id": "org_01jc5zq4m8k3v6x9t2w7r0b1e4",
      "project_id": "prj_01jc5zq4m8k3v6x9t2w7r0b1e4",
      "name": "string",
      "kind": "pod",
      "size_gb": 1,
      "region": "string",
      "status": "creating",
      "pinned_to_host": true,
      "owner_pod_id": "string",
      "usage": {
        "used_bytes": 1,
        "size_bytes": 1,
        "observed_at": "2026-01-01T00:00:00.000Z"
      },
      "attachments": [
        {
          "pod_id": "string",
          "mount_path": "string",
          "read_only": true
        }
      ],
      "endpoint_attachments": [
        {
          "endpoint_id": "string",
          "mount_path": "string",
          "read_only": true
        }
      ],
      "billing": {
        "meter": "storage_gb_second",
        "price_key": "string",
        "billed_until": "2026-01-01T00:00:00.000Z"
      },
      "created_at": "2026-01-01T00:00:00.000Z",
      "updated_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.