# Stop a sandbox

> 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.

`POST https://api.zavu.dev/v1/sandboxes/{sandboxId}/stop`

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.

## Parameters

- `sandboxId` (path, string, required): Sandbox ID.

## Responses

### 200

Already stopped, or not running.

- `sandbox` (object, required): 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.
  - `id` (string, required)
  - `name` (string, nullable): Your label for it, set with `name` on create. Copies keep their source's name.
  - `status` (string, required): - `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 of: `starting`, `running`, `stopping`, `stopped`, `failed`.
  - `size` (string, required): 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 of: `small`, `default`, `large`.
  - `timeoutSeconds` (integer, required, nullable): 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.
  - `ephemeral` (boolean, required): 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`.
  - `metadata` (object, required): What you attached when creating it. Kept by Zavu only; never visible inside the machine.
    - `{key}` (string)
  - `startedAt` (string<date-time>, nullable): When the current or last run was accepted.
  - `stoppedAt` (string<date-time>, nullable): When the last run ended. Null while starting or running.
  - `expiresAt` (string<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`.
  - `stopReason` (string, required, nullable): 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 of: `requested`, `timeout`, `insufficient_balance`, `spend_cap_reached`, `plan`, `provider`, `null`.
  - `costTotal` (number, required): 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.
  - `failureReason` (string, nullable): Why it failed. Present only when `status` is `failed`.
  - `forkedFromSandboxId` (string, nullable): The sandbox this one is a copy of, when it was made with `POST /v1/sandboxes/{sandboxId}/fork`.
  - `fromSnapshotId` (string, nullable): The project's saved snapshot it started from. Null when it started blank, as a copy, or from another team's shared snapshot.
  - `createdAt` (string<date-time>, required)
  - `updatedAt` (string<date-time>, required)

### 202

Stopping. Billing has ended.

- `sandbox` (object, required): 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.
  - `id` (string, required)
  - `name` (string, nullable): Your label for it, set with `name` on create. Copies keep their source's name.
  - `status` (string, required): - `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 of: `starting`, `running`, `stopping`, `stopped`, `failed`.
  - `size` (string, required): 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 of: `small`, `default`, `large`.
  - `timeoutSeconds` (integer, required, nullable): 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.
  - `ephemeral` (boolean, required): 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`.
  - `metadata` (object, required): What you attached when creating it. Kept by Zavu only; never visible inside the machine.
    - `{key}` (string)
  - `startedAt` (string<date-time>, nullable): When the current or last run was accepted.
  - `stoppedAt` (string<date-time>, nullable): When the last run ended. Null while starting or running.
  - `expiresAt` (string<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`.
  - `stopReason` (string, required, nullable): 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 of: `requested`, `timeout`, `insufficient_balance`, `spend_cap_reached`, `plan`, `provider`, `null`.
  - `costTotal` (number, required): 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.
  - `failureReason` (string, nullable): Why it failed. Present only when `status` is `failed`.
  - `forkedFromSandboxId` (string, nullable): The sandbox this one is a copy of, when it was made with `POST /v1/sandboxes/{sandboxId}/fork`.
  - `fromSnapshotId` (string, nullable): The project's saved snapshot it started from. Null when it started blank, as a copy, or from another team's shared snapshot.
  - `createdAt` (string<date-time>, required)
  - `updatedAt` (string<date-time>, required)

### 401

Unauthorized.

- `code` (string, required)
- `message` (string, required)
- `details` (object)

### 404

Sandbox not found, or it belongs to another project.

- `code` (string, required)
- `message` (string, required)
- `details` (object)

## Example

```bash
curl -X POST "https://api.zavu.dev/v1/sandboxes/sandbox_abc123/stop" \
  -H "Authorization: Bearer $ZAVUDEV_API_KEY"
```

```typescript
import Zavudev from "@zavudev/sdk";

const zavu = new Zavudev({ apiKey: process.env.ZAVUDEV_API_KEY });

const result = await zavu.sandboxes.stop("sandbox_abc123");

console.log(result);
```