Skip to content
Hayonix

API reference · Sandboxes

Move its deadline later (never past its maximum lifetime)

POST/v1/sandboxes/{sandbox_id}/extend
API keysandbox:updateProject
TypeScript
client.sandboxes.extend()
Python
client.sandboxes.extend()
CLI
hayonix sandboxes extend

Adds seconds to the deadline (counted from now if the deadline has passed), capped at lifetime.max_expires_at, and counts as activity for the idle timeout. An ended sandbox answers 409 sandbox_ended; one already at its maximum answers 409 lifetime_limit.

Project API key (Authorization: Bearer sk_…), or a console session. Requires the sandbox: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 "$API_BASE_URL/sandboxes/sbx_01jc5zq4m8k3v6x9t2w7r0b1e4/extend" \
  -H "Authorization: Bearer $API_KEY" \
  -H "Content-Type: application/json" \
  -d '{
  "seconds": 1800
}'

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

  • sandbox_idstringrequired

    ID of the sandbox

    ID with prefix sbx_

Body

JSON (application/json): ExtendSandboxRequest.

  • secondsintegerrequired

    Added to the deadline (from now, if that is later)

    1–86400

Response

200 Sandbox — The sandbox with its new deadline

  • 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

Example response
Example response
{
  "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"
}

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.