Skip to main content
GET
List sandboxes

Authorizations

Authorization
string
header
required

An API key that starts with vms_. Make one in Settings > API keys.

Query Parameters

limit
integer
default:50
Required range: 1 <= x <= 100
cursor
string | null
Required string length: 1 - 512
state
enum<string>[]

Return only sandboxes in this state. Send the parameter more than one time to give more states.

Available options:
creating,
starting,
running,
stopping,
stopped,
error,
deleting,
deleted,
failed
name
string

Return only the sandboxes with this name. Use it to find a sandbox by its name.

Pattern: ^[a-z0-9](?:[a-z0-9-]{0,61}[a-z0-9])?$
Example:

"agent-42"

namePrefix
string

Return only sandboxes whose name starts with this text.

Pattern: ^[a-z0-9-]{1,63}$
Example:

"agent-"

label
string[]

Return only sandboxes with this label, as key:value. Send the parameter more than one time to give more labels. A sandbox must have each label.

Pattern: ^([A-Za-z0-9](?:[A-Za-z0-9._/-]{0,61}[A-Za-z0-9])?):([\s\S]{0,255})$
Example:

Return only sandboxes whose name or ID contains this text. Upper and lower case are the same.

Required string length: 1 - 100
Example:

"agent"

sort
enum<string>
default:createdAt

The field to sort by: createdAt (the default), updatedAt, or name. A sandbox with no name sorts by its ID.

Available options:
createdAt,
updatedAt,
name
order
enum<string>
default:desc

The sort order: desc (the default) or asc.

Available options:
desc,
asc
include
enum<string>[]

Add fields to the result. cost adds costMicros to each sandbox and deletedCostMicros to the page.

Available options:
cost
Example:

Response

One page of sandboxes.

data
object[]
required
nextCursor
string | null
required
deletedCostMicros
integer

The cost of the deleted sandboxes in the current month (UTC), in micro-dollars. Only with include=cost.

Required range: 0 <= x <= 9007199254740991