# List sandboxes (v2) (/docs/api-reference/sandboxes/list-sandboxes-v2)

<!-- agent-signals: reading_time_min: 3 · est_tokens: 1710 · updated: 2026-07-30 -->
Related: [List sandboxes](/docs/api-reference/sandboxes/list-sandboxes.md), [Create sandbox](/docs/api-reference/sandboxes/create-sandbox.md), [List sandbox metrics](/docs/api-reference/sandboxes/list-sandbox-metrics.md), [Get sandbox logs](/docs/api-reference/sandboxes/get-sandbox-logs.md), [Get sandbox logs (v2)](/docs/api-reference/sandboxes/get-sandbox-logs-v2.md), [Get sandbox](/docs/api-reference/sandboxes/get-sandbox.md)

# List sandboxes (v2)

`GET /v2/sandboxes`

List all sandboxes

## OpenAPI

```json
{
  "security": [
    {
      "ApiKeyAuth": []
    }
  ],
  "parameters": [
    {
      "name": "metadata",
      "in": "query",
      "description": "Metadata query used to filter the sandboxes (e.g. \"user=abc&app=prod\"). Each key and values must be URL encoded.",
      "required": false,
      "schema": {
        "type": "string"
      }
    },
    {
      "name": "state",
      "in": "query",
      "description": "Filter sandboxes by one or more states",
      "required": false,
      "schema": {
        "type": "array",
        "items": {
          "type": "string",
          "description": "State of the sandbox",
          "enum": [
            "running",
            "paused"
          ]
        }
      },
      "style": "form",
      "explode": false
    },
    {
      "name": "nextToken",
      "in": "query",
      "description": "Cursor to start the list from",
      "required": false,
      "schema": {
        "type": "string"
      }
    },
    {
      "name": "limit",
      "in": "query",
      "description": "Maximum number of items to return per page",
      "required": false,
      "schema": {
        "type": "integer",
        "format": "int32",
        "minimum": 1,
        "default": 100,
        "maximum": 100
      }
    }
  ],
  "responses": {
    "200": {
      "description": "Successfully returned all running sandboxes",
      "content": {
        "application/json": {
          "schema": {
            "type": "array",
            "items": {
              "required": [
                "templateID",
                "sandboxID",
                "clientID",
                "startedAt",
                "cpuCount",
                "memoryMB",
                "diskSizeMB",
                "endAt",
                "state",
                "envdVersion"
              ],
              "properties": {
                "templateID": {
                  "type": "string",
                  "description": "Identifier of the template from which is the sandbox created"
                },
                "alias": {
                  "type": "string",
                  "description": "Alias of the template"
                },
                "sandboxID": {
                  "type": "string",
                  "description": "Identifier of the sandbox"
                },
                "clientID": {
                  "type": "string",
                  "deprecated": true,
                  "description": "Identifier of the client"
                },
                "startedAt": {
                  "type": "string",
                  "format": "date-time",
                  "description": "Time when the sandbox was started"
                },
                "endAt": {
                  "type": "string",
                  "format": "date-time",
                  "description": "Time when the sandbox will expire"
                },
                "cpuCount": {
                  "type": "integer",
                  "format": "int32",
                  "minimum": 1,
                  "description": "CPU cores for the sandbox"
                },
                "memoryMB": {
                  "type": "integer",
                  "format": "int32",
                  "minimum": 128,
                  "description": "Memory for the sandbox in MiB"
                },
                "diskSizeMB": {
                  "type": "integer",
                  "format": "int32",
                  "minimum": 0,
                  "description": "Disk size for the sandbox in MiB"
                },
                "metadata": {
                  "additionalProperties": {
                    "type": "string",
                    "description": "Metadata of the sandbox"
                  },
                  "type": "object"
                },
                "state": {
                  "type": "string",
                  "description": "State of the sandbox",
                  "enum": [
                    "running",
                    "paused"
                  ]
                },
                "envdVersion": {
                  "type": "string",
                  "description": "Version of the envd running in the sandbox"
                },
                "volumeMounts": {
                  "type": "array",
                  "items": {
                    "type": "object",
                    "properties": {
                      "name": {
                        "type": "string",
                        "description": "Name of the volume"
                      },
                      "path": {
                        "type": "string",
                        "description": "Path of the volume"
                      }
                    },
                    "required": [
                      "name",
                      "path"
                    ]
                  }
                }
              },
              "type": "object"
            }
          }
        }
      }
    },
    "400": {
      "description": "Bad request",
      "content": {
        "application/json": {
          "schema": {
            "required": [
              "code",
              "message"
            ],
            "properties": {
              "code": {
                "type": "integer",
                "format": "int32",
                "description": "Error code"
              },
              "message": {
                "type": "string",
                "description": "Error"
              }
            },
            "type": "object"
          }
        }
      }
    },
    "401": {
      "description": "Authentication error",
      "content": {
        "application/json": {
          "schema": {
            "required": [
              "code",
              "message"
            ],
            "properties": {
              "code": {
                "type": "integer",
                "format": "int32",
                "description": "Error code"
              },
              "message": {
                "type": "string",
                "description": "Error"
              }
            },
            "type": "object"
          }
        }
      }
    },
    "500": {
      "description": "Server error",
      "content": {
        "application/json": {
          "schema": {
            "required": [
              "code",
              "message"
            ],
            "properties": {
              "code": {
                "type": "integer",
                "format": "int32",
                "description": "Error code"
              },
              "message": {
                "type": "string",
                "description": "Error"
              }
            },
            "type": "object"
          }
        }
      }
    }
  }
}
```