# Resume a sandbox

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

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

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.

## Parameters

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

## Body

- `timeoutSeconds` (integer, nullable): A new timeout for this run. `null` turns auto-stop off for this and later runs. Omit to keep the sandbox's.

## Responses

### 202

Accepted. The sandbox is starting.

- `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)

### 400

Invalid body, or the key is a test-mode key: sandboxes need a live key.

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

### 401

Unauthorized.

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

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

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

### 403

`plan_limit_reached`: the team already has 10 sandboxes starting or running. `details.limit` and `details.running` say so.

- `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)

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

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

### 429

`daily_limit_exceeded`: the team started 200 sandboxes today (creates and resumes both count). Resets at 00:00 UTC.

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

### 503

`sandbox_unavailable`: no machine capacity right now. Nothing was charged for machine time; retry shortly.

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

## Example

```bash
curl -X POST "https://api.zavu.dev/v1/sandboxes/sandbox_abc123/resume" \
  -H "Authorization: Bearer $ZAVUDEV_API_KEY" \
  -H "Content-Type: application/json" \
  -d '{
  "timeoutSeconds": 60
}'
```

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

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

const result = await zavu.sandboxes.resume("sandbox_abc123", {
  timeoutSeconds: 60,
});

console.log(result);
```