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

# List sandboxes (E2B)

E2B's `GET /v2/sandboxes`. Running and paused sandboxes of the project, newest first, filtered by `metadata` (URL-encoded `key=value` pairs joined with `&`, at most 4) and `state` (`running`, `paused`, comma-separated). Pages hold `limit` sandboxes (default 100, at most 100); the next page's token is the `x-next-token` response header. Never carries an envd access token.

` GET /compat/e2b/v2/sandboxes `

List sandboxes (E2B)

E2B's `GET /v2/sandboxes`. Running and paused sandboxes of the project, newest first, filtered by `metadata` (URL-encoded `key=value` pairs joined with `&`, at most 4) and `state` (`running`, `paused`, comma-separated). Pages hold `limit` sandboxes (default 100, at most 100); the next page's token is the `x-next-token` response header. Never carries an envd access token.

## Servers

- ` https://beta-api.b3os.org ` — API (API keys and CLI tokens)

- ` https://beta.b3os.org ` — Dashboard (session cookie and CSRF header; same paths)

## Authentication

The operation accepts these alternatives. Schemes within one alternative are required together.

### Alternative 1

- ` apiKey `: ` http `

  - HTTP scheme: ` bearer ` (b3os_sk_ API key or b3os_pat_ token)

  - `Authorization: Bearer <credential>`. Two credential kinds are accepted:

- **API keys** `b3os_sk_<32 base32>_<crc32>`, created in the dashboard or with `POST /v1/keys`. A key belongs to
  one project, has scopes, an optional spend cap and expiry, and is shown only once.
- **CLI tokens** `b3os_pat_<32 base32>_<crc32>`, issued by the device login (`b3os login`). They act for one
  user in the organization and project chosen at approval.

Keys are stored as SHA-256 hashes. The edge exchanges them for a 60-second node token before forwarding
a request to a node, so nodes never see your key.


## Parameters

### ` metadata ` (query, optional)

URL-encoded `key=value` pairs joined with `&`.

- ` value `: type ` string `

### ` state ` (query, optional)

`running`, `paused`, or both comma-separated (the default).

- ` value `: type ` string `

### ` limit ` (query, optional)

- ` value `: type ` integer `

  - minimum: ` 1 `

  - maximum: ` 100 `

### ` nextToken ` (query, optional)

The `x-next-token` header of the previous page.

- ` value `: type ` string `

## Responses

### ` 200 ` — One page of sandboxes.

Content type: ` application/json `

- ` value `: type ` array `

  - ` array item `: type ` object `

    - Required fields: ` sandboxID `, ` templateID `, ` clientID `, ` startedAt `, ` endAt `, ` cpuCount `, ` memoryMB `, ` diskSizeMB `, ` envdVersion `, ` state `

    - ` sandboxID `: type ` string `

    - ` templateID `: type ` string `

    - ` clientID `: type ` string `

    - ` startedAt `: type ` string `; format ` date-time `

    - ` endAt `: type ` string `; format ` date-time `

    - ` cpuCount `: type ` integer `

    - ` memoryMB `: type ` integer `

    - ` diskSizeMB `: type ` integer `

    - ` envdVersion `: type ` string `

    - ` metadata `: type ` object `

    - ` state `: type ` string `

      - enum: ` ["running","paused"] `

Response header ` x-request-id ` — The request ID (`req_…`). It is the `instance` of any problem and the key for `GET /v1/requests/{request_id}`.

- ` value `: type ` string `

  - pattern: ` "^req_[0-9a-hjkmnp-tv-z]{26}$" `

Response header ` Server-Timing ` — Phase durations in milliseconds (W3C Server Timing); the handler's phases break the request down. For a
response whose body size is known, `total` runs from reading the request head to writing the response head.
Streaming responses (event streams, WebSockets, chunked bodies) carry no `total` here: they report their
final phases in the terminal event (`job.succeeded`, `job.failed`, `job.canceled`) or the final job. The
time from the first request byte to the last response byte is recorded in the node's metrics and request
log (`GET /v1/requests/{request_id}`). The edge prepends `edge_auth` and `edge_upstream`.


- ` value `: type ` string `

Response header ` x-next-token ` — The token of the next page; absent on the last page.

- ` value `: type ` string `

Example:

```json
[
  {
    "sandboxID": "sbx-01m5t68q1b590rj801nbzsqzkk",
    "templateID": "base",
    "clientID": "b3os",
    "startedAt": "2026-11-02T13:00:00.000Z",
    "endAt": "2026-11-02T13:05:00.000Z",
    "cpuCount": 1,
    "memoryMB": 512,
    "diskSizeMB": 4096,
    "envdVersion": "0.5.7",
    "metadata": {
      "run": "demo"
    },
    "state": "running"
  }
]
```

### ` 400 ` — A malformed value, or an option B3OS cannot honor named in the message (`invalid_request`, `unsupported_option`).

Content type: ` application/json `

- ` value `: type ` object ` — E2B's error body.

  - Required fields: ` code `, ` message `

  - ` code `: type ` integer ` — The HTTP status.

  - ` message `: type ` string `

Response header ` x-request-id ` — The request ID (`req_…`). It is the `instance` of any problem and the key for `GET /v1/requests/{request_id}`.

- ` value `: type ` string `

  - pattern: ` "^req_[0-9a-hjkmnp-tv-z]{26}$" `

Response header ` Server-Timing ` — Phase durations in milliseconds (W3C Server Timing); the handler's phases break the request down. For a
response whose body size is known, `total` runs from reading the request head to writing the response head.
Streaming responses (event streams, WebSockets, chunked bodies) carry no `total` here: they report their
final phases in the terminal event (`job.succeeded`, `job.failed`, `job.canceled`) or the final job. The
time from the first request byte to the last response byte is recorded in the node's metrics and request
log (`GET /v1/requests/{request_id}`). The edge prepends `edge_auth` and `edge_upstream`.


- ` value `: type ` string `

Example:

```json
{
  "code": 400,
  "message": "mcp is not supported by B3OS: run your MCP server as a process in the sandbox"
}
```

### ` 401 ` — Missing or invalid B3OS key in `X-API-KEY` (`unauthorized`).

Content type: ` application/json `

- ` value `: type ` object ` — E2B's error body.

  - Required fields: ` code `, ` message `

  - ` code `: type ` integer ` — The HTTP status.

  - ` message `: type ` string `

Response header ` x-request-id ` — The request ID (`req_…`). It is the `instance` of any problem and the key for `GET /v1/requests/{request_id}`.

- ` value `: type ` string `

  - pattern: ` "^req_[0-9a-hjkmnp-tv-z]{26}$" `

Response header ` Server-Timing ` — Phase durations in milliseconds (W3C Server Timing); the handler's phases break the request down. For a
response whose body size is known, `total` runs from reading the request head to writing the response head.
Streaming responses (event streams, WebSockets, chunked bodies) carry no `total` here: they report their
final phases in the terminal event (`job.succeeded`, `job.failed`, `job.canceled`) or the final job. The
time from the first request byte to the last response byte is recorded in the node's metrics and request
log (`GET /v1/requests/{request_id}`). The edge prepends `edge_auth` and `edge_upstream`.


- ` value `: type ` string `

Example:

```json
{
  "code": 401,
  "message": "unknown key"
}
```

## Request examples

### cURL

```curl
curl -X GET 'https://beta-api.b3os.org/compat/e2b/v2/sandboxes' \
  -H 'Authorization: Bearer YOUR_API_TOKEN'
```

### JavaScript

```javascript
const response = await fetch('https://beta-api.b3os.org/compat/e2b/v2/sandboxes', {
  method: 'GET',
  headers: {
      "Authorization": "Bearer YOUR_API_TOKEN"
  }
});

const data = await response.json();
console.log(data);
```

### Python

```python
import requests

headers = {
    'Authorization': 'Bearer YOUR_API_TOKEN'
}

response = requests.get('https://beta-api.b3os.org/compat/e2b/v2/sandboxes', headers=headers)
print(response.json())
```