> ## Documentation Index
> Fetch the complete documentation index at: https://vms.dev/docs/llms.txt
> Use this file to discover all available pages before exploring further.

# List, find, and label sandboxes

> Give sandboxes names and labels, find a sandbox by its name, list sandboxes page by page, and create or delete many sandboxes in one request.

Give each sandbox a name and labels. Then find a sandbox by its name, or list the sandboxes that have a label.

Write the code that names, finds, and lists sandboxes.

Create a sandbox with POST /v1/sandboxes and send a name and labels.
If the API answers 409 sandbox\_name\_taken, read the sandbox in error.sandboxId.
Find a sandbox by its name with GET /v1/sandboxes?name=agent-42.
List sandboxes with GET /v1/sandboxes and the label filter, and read each page with nextCursor.
Do not ask me to share my API key.

## Before you start

* To read and list sandboxes, you need an API key with the `sandboxes:read` scope. To create, change, or delete sandboxes, you need `sandboxes:write`. See [API keys](https://vms.dev/docs/workspace/api-keys.md).
* Read [Create, get, and delete a sandbox](https://vms.dev/docs/sandboxes/create-and-delete.md) first.

## Give a sandbox a name and labels

Send `name` and `labels` in the body of `POST /v1/sandboxes`:

```typescript TypeScript theme={null}
const response = await fetch("https://vms.dev/api/v1/sandboxes", {
  method: "POST",
  headers: {
    Authorization: `Bearer ${process.env.VMS_API_KEY}`,
    "Content-Type": "application/json",
    "Idempotency-Key": crypto.randomUUID(),
  },
  body: JSON.stringify({
    size: "small",
    name: "agent-42",
    labels: { project: "web", agent: "reviewer" },
  }),
});

const sandbox = await response.json();
```

```bash cURL theme={null}
curl https://vms.dev/api/v1/sandboxes \
  -H "Authorization: Bearer $VMS_API_KEY" \
  -H "Content-Type: application/json" \
  -H "Idempotency-Key: $(uuidgen)" \
  -d '{"size": "small", "name": "agent-42", "labels": {"project": "web", "agent": "reviewer"}}'
```

A name has these rules:

* It has 1 to 63 characters: lowercase letters, digits, and hyphens.
* It cannot start or end with a hyphen.
* It is unique in the workspace. Two workspaces can use the same name.

Labels have these rules:

* A sandbox can have up to 50 labels.
* A key has 1 to 63 characters: letters, digits, and the characters `.` `_` `/` `-`. It starts and ends with a letter or a digit.
* A value has up to 255 characters.

### When the name is in use

If another sandbox in the workspace has the name, the API answers `409` with the code `sandbox_name_taken`. The `sandboxId` field gives the sandbox that has the name:

```json theme={null}
{
  "error": {
    "code": "sandbox_name_taken",
    "message": "Another sandbox in this workspace has this name. Use a different name, or delete the other sandbox.",
    "requestId": "19283a6c-8864-483f-8dab-320eec5015e1",
    "sandboxId": "sbx_06d8k3m7q2v9x4b1n5c0e8f2ja"
  }
}
```

A sandbox releases its name when it is `failed`, `deleting`, or `deleted`. Then a new sandbox can use the name. For example, a create that answers `503 no_capacity` does not keep the name, so a retry can use it.

## Change the name or the labels

Send `PATCH /v1/sandboxes/{id}` with the fields to change. The API changes only the fields that you send:

* `name` sets a new name. `null` removes the name.
* `labels` replaces all labels of the sandbox. `{}` removes all labels.

```typescript TypeScript theme={null}
const response = await fetch(`https://vms.dev/api/v1/sandboxes/${sandbox.id}`, {
  method: "PATCH",
  headers: {
    Authorization: `Bearer ${process.env.VMS_API_KEY}`,
    "Content-Type": "application/json",
  },
  body: JSON.stringify({ labels: { project: "web", stage: "review" } }),
});

console.log((await response.json()).labels);
```

```bash cURL theme={null}
curl -X PATCH https://vms.dev/api/v1/sandboxes/sbx_06d8k3m7q2v9x4b1n5c0e8f2ja \
  -H "Authorization: Bearer $VMS_API_KEY" \
  -H "Content-Type: application/json" \
  -d '{"labels": {"project": "web", "stage": "review"}}'
```

The API answers `200` with the changed sandbox. A name that another sandbox has answers `409 sandbox_name_taken`.

The same request also takes `state` to stop or resume the sandbox. See [Stop and resume a sandbox](https://vms.dev/docs/sandboxes/stop-and-resume.md).

## Find a sandbox by its name

Send `GET /v1/sandboxes` with the `name` parameter:

```typescript TypeScript theme={null}
const response = await fetch("https://vms.dev/api/v1/sandboxes?name=agent-42", {
  headers: { Authorization: `Bearer ${process.env.VMS_API_KEY}` },
});

const { data } = await response.json();
const sandbox = data[0];
```

```bash cURL theme={null}
curl "https://vms.dev/api/v1/sandboxes?name=agent-42" \
  -H "Authorization: Bearer $VMS_API_KEY"
```

The list is newest first. A sandbox that is `failed` or `deleting` can have the same name as a newer sandbox. To get only sandboxes that you can use, also send `state`, for example `state=running&state=stopped`.

## List sandboxes

`GET /v1/sandboxes` returns one page of sandboxes, newest first by default. A deleted sandbox is not in the list. Use these query parameters:

| Parameter | Value |
| - | - |
| `limit` | The number of sandboxes on the page, 1 to 100. The default is 50. |
| `cursor` | The `nextCursor` of the last page. |
| `state` | A state, such as `running`. Send the parameter more than one time for more states. |
| `name` | A full name. |
| `namePrefix` | The start of a name, such as `agent-`. |
| `label` | A label as `key:value`, such as `project:web`. Send the parameter more than one time for more labels. A sandbox must have each label. |
| `search` | Text in the name or the ID, such as `agent`. Upper and lower case are the same. |
| `sort` | `createdAt` (the default), `updatedAt`, or `name`. A sandbox with no name sorts by its ID. |
| `order` | `desc` (the default) or `asc`. |
| `include` | `cost` adds the cost of each sandbox this month. See [List the cost of each sandbox](#list-the-cost-of-each-sandbox). |

The response has `data`, the sandboxes, and `nextCursor`. If `nextCursor` is `null`, the page is the last page. To get the next page, send the same parameters with `cursor` set to `nextCursor`:

```typescript TypeScript theme={null}
const sandboxes = [];
let cursor: string | null = null;

do {
  const query = new URLSearchParams({ label: "project:web", limit: "100" });

  if (cursor) query.set("cursor", cursor);

  const response = await fetch(`https://vms.dev/api/v1/sandboxes?${query}`, {
    headers: { Authorization: `Bearer ${process.env.VMS_API_KEY}` },
  });
  const page = await response.json();

  sandboxes.push(...page.data);
  cursor = page.nextCursor;
} while (cursor);
```

```bash cURL theme={null}
curl "https://vms.dev/api/v1/sandboxes?label=project:web&state=running&limit=100" \
  -H "Authorization: Bearer $VMS_API_KEY"
```

## List the cost of each sandbox

Add `include=cost` to `GET /v1/sandboxes`. Each sandbox gets `costMicros`, its cost since the first day of the month (UTC). The page gets `deletedCostMicros`, the cost of the deleted sandboxes this month. Amounts are in micro-dollars: 1,000,000 is \$1.

```bash theme={null}
curl "https://vms.dev/api/v1/sandboxes?include=cost&label=project:web" \
  -H "Authorization: Bearer $VMS_API_KEY"
```

For the cost of one sandbox in a different window, see [Read the usage with the API](https://vms.dev/docs/workspace/usage-and-balance.md#read-the-usage-with-the-api).

## Create or delete many sandboxes

Send `POST /v1/sandboxes/create-many` with `items`, a list of 1 to 500 creates. Each item has the fields of a create. Send `POST /v1/sandboxes/delete-many` with `ids`, a list of 1 to 500 sandbox IDs.

```typescript TypeScript theme={null}
const headers = {
  Authorization: `Bearer ${process.env.VMS_API_KEY}`,
  "Content-Type": "application/json",
};

const created = await fetch("https://vms.dev/api/v1/sandboxes/create-many", {
  method: "POST",
  headers,
  body: JSON.stringify({
    items: [
      { size: "small", labels: { run: "test-7" } },
      { size: "small", labels: { run: "test-7" } },
    ],
  }),
}).then((response) => response.json());

const ids = created.data.flatMap((row) => (row.id ? [row.id] : []));

await fetch("https://vms.dev/api/v1/sandboxes/delete-many", {
  method: "POST",
  headers,
  body: JSON.stringify({ ids }),
});
```

```bash cURL theme={null}
curl https://vms.dev/api/v1/sandboxes/create-many \
  -H "Authorization: Bearer $VMS_API_KEY" \
  -H "Content-Type: application/json" \
  -d '{"items": [{"size": "small"}, {"size": "small"}]}'

curl https://vms.dev/api/v1/sandboxes/delete-many \
  -H "Authorization: Bearer $VMS_API_KEY" \
  -H "Content-Type: application/json" \
  -d '{"ids": ["sbx_06d8k3m7q2v9x4b1n5c0e8f2ja", "sbx_06d8k3m7q2v9x4b1n5c0e8f2jb"]}'
```

The API does the items one after the other. It answers `200` with a result for each item, in the sequence of the request:

```json theme={null}
{
  "succeeded": 1,
  "failed": 1,
  "message": "No host has room for a sandbox of this size now. Try again later.",
  "data": [
    { "index": 0, "id": "sbx_06d8k3m7q2v9x4b1n5c0e8f2ja", "error": null },
    { "index": 1, "id": null, "error": "No host has room for a sandbox of this size now. Try again later." }
  ]
}
```

* For a create, `id` is the ID of the new sandbox. If the create failed, `id` is `null` and `error` gives the reason.
* For a delete, `id` is the ID that you sent. If the delete failed, `error` gives the reason.
* `message` is the first error, or `null`.

A create in `create-many` takes no `Idempotency-Key`. Each new sandbox moves to `running` as a single create does. Each deleted sandbox moves to `deleting`, then to `deleted`.

Read the [changelog.](https://vms.dev/docs/changelog.md)


This documentation is built and hosted on [Mintlify](https://mintlify.com), a developer documentation platform.