Skip to main content
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.

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.
  • Read Create, get, and delete a sandbox first.

Give a sandbox a name and labels

Send name and labels in the body of POST /v1/sandboxes:
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:
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.
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.

Find a sandbox by its name

Send GET /v1/sandboxes with the name parameter:
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: 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:

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.
For the cost of one sandbox in a different window, see 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.
The API does the items one after the other. It answers 200 with a result for each item, in the sequence of the request:
  • 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.