List Sandboxes

GET /v1/sessions/sandboxes

List VMs (sandboxes) with optional metadata filtering.

This endpoint matches E2B's Sandbox.list() functionality.

Args: metadata: JSON string of key-value pairs to filter by. Example: '{"userId": "123", "env": "dev"}' Filters using @> (contains) operator for GIN-indexed queries. limit: Maximum number of results (1-1000, default: 100)

Returns: List of sandbox info objects with:

• sandbox_id: Unique VM identifier
• template_id: Snapshot/template used (from parent_snapshot_ref)
• name: Template name (from parent_snapshot_ref or "default")
• metadata: User-defined key-value pairs
• started_at: ISO timestamp when VM was started
• end_at: ISO timestamp when VM will expire (if active)
• status: VM status ('active', 'killed', etc.)

Example: GET /v1/sessions/sandboxes?metadata={"userId":"123"}

Response: [ { "sandbox_id": "vmid-abc-15", "template_id": "snap2", "name": "snap2", "metadata": {"userId": "123", "env": "dev"}, "started_at": "2025-01-18T10:30:00", "end_at": "2025-01-18T10:35:00", "status": "active" } ]

Authentication

Requires authentication via: OAuth2PasswordBearer.

Parameters

Name	In	Type	Required	Description	Constraints
metadata	query	string | null	No	JSON string of metadata filters, e.g. '{"userId":"123"}'	nullable
limit	query	integer	No	Maximum number of results	default=100, min=1, max=1000
X-API-Key	header	string | null	No		nullable

Responses

200

Successful Response

application/json

Resolved schema:

{
  "type": "array",
  "items": {
    "properties": {
      "sandbox_id": {
        "type": "string",
        "title": "Sandbox Id"
      },
      "template_id": {
        "anyOf": [
          {
            "type": "string"
          },
          {
            "type": "null"
          }
        ],
        "title": "Template Id"
      },
      "name": {
        "type": "string",
        "title": "Name"
      },
      "metadata": {
        "type": "object",
        "title": "Metadata"
      },
      "started_at": {
        "type": "string",
        "title": "Started At"
      },
      "end_at": {
        "anyOf": [
          {
            "type": "string"
          },
          {
            "type": "null"
          }
        ],
        "title": "End At"
      },
      "status": {
        "type": "string",
        "title": "Status"
      }
    },
    "type": "object",
    "required": [
      "sandbox_id",
      "name",
      "metadata",
      "started_at",
      "status"
    ],
    "title": "VMSandboxInfo",
    "description": "Response model matching E2B's SandboxInfo structure."
  },
  "title": "Response List Sandboxes V1 Sessions Sandboxes Get"
}

Field details:

Field	Type	Required	Description	Constraints
[]	object	Yes	Response model matching E2B's SandboxInfo structure.
[].sandbox_id	string	Yes
[].template_id	string | null	No		nullable
[].name	string	Yes
[].metadata	object	Yes
[].started_at	string	Yes
[].end_at	string | null	No		nullable
[].status	string	Yes

422

Validation Error

application/json

Resolved schema:

{
  "properties": {
    "detail": {
      "items": {
        "properties": {
          "loc": {
            "items": {
              "anyOf": [
                {
                  "type": "string"
                },
                {
                  "type": "integer"
                }
              ]
            },
            "type": "array",
            "title": "Location"
          },
          "msg": {
            "type": "string",
            "title": "Message"
          },
          "type": {
            "type": "string",
            "title": "Error Type"
          }
        },
        "type": "object",
        "required": [
          "loc",
          "msg",
          "type"
        ],
        "title": "ValidationError"
      },
      "type": "array",
      "title": "Detail"
    }
  },
  "type": "object",
  "title": "HTTPValidationError"
}

Field details:

Field	Type	Required	Description	Constraints
detail	array<object>	No
detail[]	object	No
detail[].loc	array<string | integer>	No
detail[].loc[]	string | integer	No
detail[].msg	string	No
detail[].type	string	No