Skip to content
DashboardGet API key

Resume a sandbox

View .md
POST

Start a stopped sandbox again with its disk as it was. Billed like a create: $0.01, then machine time, and it passes the same checks. Not available with test-mode keys.

Authorization

  • Authorizationheaderrequired

    Bearer YOUR_API_KEY. Create a key in the dashboard.

Path parameters

  • sandboxIdstringrequired

    Sandbox ID.

Body

application/json · optional

  • timeoutSecondsintegernullable

    A new timeout for this run. null turns auto-stop off for this and later runs. Omit to keep the sandbox's.

    Limitsmin 60 · max 86400

Responses

202Accepted. The sandbox is starting.
  • sandboxobjectrequired

    An isolated Linux machine. It is billed per second while starting or running (with a one-minute minimum per run), plus $0.01 each time it is created or resumed. A stopped sandbox costs nothing.

    17 properties
    • idstringrequired
    • namestringnullable

      Your label for it, set with name on create. Copies keep their source's name.

    • statusstringrequired
      • starting: accepted, the machine is being prepared. Commands and file calls wait for it.
      • running: the machine is up. Machine time is billed.
      • stopping: a stop was requested; billing already ended.
      • stopped: the disk is kept until expiresAt, and POST /resume starts it again. Not billed.
      • failed: the machine could not start or failed on its host. See failureReason. A sandbox that fails before it ever runs gets its start fee back.
      One ofstartingrunningstoppingstoppedfailed
    • sizestringrequired

      Machine size, and its price per hour of machine time: - small: 2 vCPU, 4 GB RAM. $0.0225/h. - default: 4 vCPU, 8 GB RAM. $0.045/h. - large: 8 vCPU, 16 GB RAM. $0.09/h.

      One ofsmalldefaultlarge
    • timeoutSecondsintegerrequirednullable

      The sandbox is stopped automatically this many seconds after it started (or was last resumed). Checked every minute. null when auto-stop is off: it runs until you stop it, or until the balance, the spend cap or leaving the paid plan stops it.

    • ephemeralbooleanrequired

      Created with ephemeral: true. Its disk is never saved: a stop erases it, expiresAt is the moment it stopped, and resume answers 409 sandbox_expired.

    • metadataobjectrequired

      What you attached when creating it. Kept by Zavu only; never visible inside the machine.

      1 properties
      • {key}string
    • startedAtstring<date-time>nullable

      When the current or last run was accepted.

    • stoppedAtstring<date-time>nullable

      When the last run ended. Null while starting or running.

    • expiresAtstring<date-time>nullable

      Present while stopped: when the disk is deleted, 14 days after the stop, or the stop itself for an ephemeral sandbox. After it, resume answers 409 sandbox_expired.

    • stopReasonstringrequirednullable

      Why the last run ended, while stopping or stopped; null otherwise. requested: you stopped it, from the API or the dashboard. timeout: its timeoutSeconds passed. insufficient_balance and spend_cap_reached: the balance or the monthly spend cap no longer covered 15 more minutes. plan: the team left its paid plan. provider: it ended on its host. The sandbox.stopped project webhook carries the same value.

      One ofrequestedtimeoutinsufficient_balancespend_cap_reachedplanprovidernull
    • costTotalnumberrequired

      USD charged for this sandbox so far: start fees plus machine time. Machine time of a running sandbox is settled every five minutes, so this lags by up to five minutes until it stops.

    • failureReasonstringnullable

      Why it failed. Present only when status is failed.

    • forkedFromSandboxIdstringnullable

      The sandbox this one is a copy of, when it was made with POST /v1/sandboxes/{sandboxId}/fork.

    • fromSnapshotIdstringnullable

      The project's saved snapshot it started from. Null when it started blank, as a copy, or from another team's shared snapshot.

    • createdAtstring<date-time>required
    • updatedAtstring<date-time>required
400Invalid body, or the key is a test-mode key: sandboxes need a live key.
  • codestringrequired
  • messagestringrequired
  • detailsobject
401Unauthorized.
  • codestringrequired
  • messagestringrequired
  • detailsobject
402`paid_plan_required`: sandboxes need a paid plan, and Free cannot start one (`details.dashboardUrl` is `/upgrade`). `insufficient_balance`: the balance does not cover the $0.01 start fee plus 15 minutes of machine time at the sandbox's size. `spend_cap_reached`: the monthly spend cap does not leave that much room.
  • codestringrequired
  • messagestringrequired
  • detailsobject
403`plan_limit_reached`: the team already has 10 sandboxes starting or running. `details.limit` and `details.running` say so.
  • codestringrequired
  • messagestringrequired
  • detailsobject
404Sandbox not found, or it belongs to another project.
  • codestringrequired
  • messagestringrequired
  • detailsobject
409`sandbox_not_stopped`: only a `stopped` sandbox can be resumed. `sandbox_expired`: its disk was deleted, 14 days after it stopped or, for an ephemeral sandbox, at the stop itself; create a new one. Nothing is charged.
  • codestringrequired
  • messagestringrequired
  • detailsobject
429`daily_limit_exceeded`: the team started 200 sandboxes today (creates and resumes both count). Resets at 00:00 UTC.
  • codestringrequired
  • messagestringrequired
  • detailsobject
503`sandbox_unavailable`: no machine capacity right now. Nothing was charged for machine time; retry shortly.
  • codestringrequired
  • messagestringrequired
  • detailsobject