Skip to main content
GET
List sandboxes

Authorizations

Authorization
string
header
required

Boat bearer token in the form boat_.... Service API keys authenticate sandbox operations.

Headers

X-Boat-Org
string

Same as the org query parameter. Query wins when both are set.

Query Parameters

org
string

Billing wallet for this request: an organization you belong to, by id (team_…) or by name as GET /orgs lists it (case-insensitive), or personal. Omitted, the account's active wallet applies (PATCH /orgs/active; personal until set). Two organizations sharing the name answer 409 ambiguous_org and need the id. Sandboxes and snapshots stay creator-private. On /environments routes, only this query parameter selects the organization's shared environments; the X-Boat-Org header and the active wallet do not apply there. Members read them, owners and admins change them.

limit
integer
default:100

Maximum items to return.

Required range: 1 <= x <= 200
cursor
string | null

Opaque pagination cursor returned as pageInfo.nextCursor.

sort
enum<string>
default:desc

Sort direction for cursor pagination.

Available options:
asc,
desc
state
string

Comma-separated sandbox state filter, for example ready,idle,running.

namePrefix
string

Keep sandboxes whose name starts with this text, for example myapp-. The match is literal.

stoppedBefore
string<date-time>

Keep stopped sandboxes that stopped before this ISO 8601 time. Every stop counts, auto-stops too.

dataExpired
boolean

true keeps sandboxes whose data retention deleted (dataExpiredAt is set). false keeps the others.

label
string[]

key=value. Repeat it to require several labels, for example label=session%3Dabc&label=env%3Dprod.

include
enum<string>

cost adds each sandbox's cost this calendar month (UTC), at list price.

Available options:
cost

Response

Sandboxes owned by the authenticated Boat user.

ok
boolean
required
Example:

true

type
string
required

Stable success envelope discriminator added by v1.

Allowed value: "sandbox.list"
sandboxes
object[]
required
pageInfo
object
deletedCost
object

Only with include=cost, and not for an API key limited to some sandboxes. Machine time this calendar month (UTC) of deleted sandboxes this list would otherwise show. They are not in the list, but their time was billed. Add it to the sandboxes' cost to get the full total.