Skip to content
Hayonix

API reference · Sandboxes

List sandboxes in the project, newest first (ended ones only when asked for)

GET/v1/sandboxes
API keysandbox:readProjectPaginated
TypeScript
client.sandboxes.list()
Python
client.sandboxes.list()
CLI
hayonix sandboxes list

Returns the sandboxes that have not ended, with their state, time left and cost so far; pass include_ended=true to list ended ones as well.

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

    Also list sandboxes that have ended (default false)

Response

200 a page of results — A page of sandboxes

  • dataarray of Sandboxrequired

    The items of this page.

    Show 17 fields of data
    • objectstringrequired

      Always `sandbox`: the type of this object

      One ofsandbox

    • idstringrequired

      Unique ID (`sbx_…`)

      ID with prefix sbx_

    • org_idstringrequired

      Organization it belongs to

      ID with prefix org_

    • project_idstringrequired

      Project it belongs to

      ID with prefix prj_

    • namestringrequired

      Its name

    • statusSandboxStatusrequired
      Show 4 fields of status
      • statestringrequired

        starting | ready (waiting for code) | busy (running code) | unreachable (its host stopped reporting) | ending | ended | failed

        One ofstartingreadybusyunreachableendingendedfailed

      • reasonstringrequired

        Machine-readable cause, lower_snake_case

      • messagestringrequired

        One sentence for people

      • sincestring (date-time)required

        When it entered this state (ISO 8601, UTC)

    • sizeobjectrequired

      The size it was created with

      Show 4 fields of size
      • codestringrequired

        Machine-readable code

      • display_namestring | nullrequired

        Name to show people

      • vcpusinteger | nullrequired

        Virtual CPUs (null if the size is no longer listed)

      • memory_gbinteger | nullrequired

        Memory in GB (null if the size is no longer listed)

    • regionstringrequired

      Region code

    • priceobjectrequired

      Its price, fixed when it was created

      Show 2 fields of price
      • per_secondstringrequired

        Price per second of running, nano-USD (what is billed)

        pattern ^-?[0-9]+$

      • per_hourstringrequired

        The same price per hour (per_second × 3600), nano-USD

        pattern ^-?[0-9]+$

    • usageobjectrequired

      What it has cost so far

      Show 2 fields of usage
      • billed_secondsstringrequired

        Running time billed so far, in seconds (decimal string)

      • cost_so_farstringrequired

        Cost of that running time, nano-USD; can lag a few seconds behind

        pattern ^-?[0-9]+$

    • lifetimeobjectrequired

      When it ends, and what keeps it alive

      Show 5 fields of lifetime
      • expires_atstring (date-time)required

        When it ends by itself

      • idle_timeout_secondsintegerrequired

        It ends after this many seconds without a run or a file operation

      • idle_expires_atstring (date-time) | nullrequired

        When the idle timeout ends it if nothing runs and no file is touched before then (null once ended)

      • last_activity_atstring (date-time)required

        Time last activity (ISO 8601, UTC)

      • max_expires_atstring (date-time)required

        The latest an extension can reach

    • runsobjectrequired

      Run counts

      Show 2 fields of runs
      • activeintegerrequired

        Runs queued or running now

      • totalintegerrequired

        Runs sent to it over its life, in any state

    • metadataobjectrequired

      Your own key/value labels, returned as given

    • created_atstring (date-time)required

      When it was created (ISO 8601, UTC)

    • started_atstring (date-time) | nullrequired

      When it first started running

    • ended_atstring (date-time) | nullrequired

      When it ended (null until then) (ISO 8601, UTC)

    • end_reasonstring | nullrequired

      requested | expired | idle | billing | suspended | host_maintenance | host_lost | failed

      One ofrequestedexpiredidlebillingsuspendedhost_maintenancehost_lostfailed

  • next_cursorstring | nullrequired

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

Example response
Example response
{
  "data": [
    {
      "object": "sandbox",
      "id": "sbx_01jc5zq4m8k3v6x9t2w7r0b1e4",
      "org_id": "org_01jc5zq4m8k3v6x9t2w7r0b1e4",
      "project_id": "prj_01jc5zq4m8k3v6x9t2w7r0b1e4",
      "name": "string",
      "status": {
        "state": "starting",
        "reason": "string",
        "message": "string",
        "since": "2026-01-01T00:00:00.000Z"
      },
      "size": {
        "code": "cpu-2c-4gb",
        "display_name": "string",
        "vcpus": 1,
        "memory_gb": 1
      },
      "region": "string",
      "price": {
        "per_second": "1500000000",
        "per_hour": "1500000000"
      },
      "usage": {
        "billed_seconds": "string",
        "cost_so_far": "1500000000"
      },
      "lifetime": {
        "expires_at": "2026-01-01T00:00:00.000Z",
        "idle_timeout_seconds": 1,
        "idle_expires_at": "2026-01-01T00:00:00.000Z",
        "last_activity_at": "2026-01-01T00:00:00.000Z",
        "max_expires_at": "2026-01-01T00:00:00.000Z"
      },
      "runs": {
        "active": 1,
        "total": 1
      },
      "metadata": {},
      "created_at": "2026-01-01T00:00:00.000Z",
      "started_at": "2026-01-01T00:00:00.000Z",
      "ended_at": "2026-01-01T00:00:00.000Z",
      "end_reason": "requested"
    }
  ],
  "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.