Skip to content
DashboardGet API key

Stop a sandbox

View .md
POST

End the run and keep the disk, so resume can start it again within 14 days. An ephemeral sandbox's disk is erased instead. Billing ends when this is called. Works with test-mode keys and on any plan.

Answers 202 while the machine shuts down (stopping), or 200 when it is already stopped or was never running.

Authorization

  • Authorizationheaderrequired

    Bearer YOUR_API_KEY. Create a key in the dashboard.

Path parameters

  • sandboxIdstringrequired

    Sandbox ID.

Responses

200Already stopped, or not running.
  • 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
202Stopping. Billing has ended.
  • 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
401Unauthorized.
  • codestringrequired
  • messagestringrequired
  • detailsobject
404Sandbox not found, or it belongs to another project.
  • codestringrequired
  • messagestringrequired
  • detailsobject