---
title: "List sandboxes"
method: GET
path: "/api/v2/sandboxes/boxes"
tags: ["sandboxes"]
---

# List sandboxes

`GET /api/v2/sandboxes/boxes`

## Request

- Base URL: `https://api.smith.langchain.com`
- URL: `https://api.smith.langchain.com/api/v2/sandboxes/boxes`
- Auth: one of:
  - API key in header `X-API-Key`
  - API key in header `X-Tenant-Id`
  - HTTP bearer
  - `X-Service-Key` (a scheme the document does not define)

List sandboxes for the authenticated tenant, with optional filtering, sorting, and pagination.
Page with page_size and cursor: replay the response's next_cursor until it comes back null, which is the only signal that no pages remain.
Cursors are opaque and only valid on this endpoint; do not parse or construct one.

## Query parameters

- `page_size` integer
- `cursor` string
- `limit` integer
- `offset` integer
- `name_contains` string
- `status` string
- `tag_value_id` string[]
- `created_by` string
- `label` string[]
- `sort_by` string
- `sort_order` string
- `sort_direction` string

## Response `200`

OK

- SandboxesSandboxListResponse
  - `items` SandboxesSandboxResponse[]: This page of sandboxes.
    - `access_delegation` SandboxesAccessDelegation
      - `mode` 'INHERIT' | 'EXPLICIT', required
      - `permissions` string[]
    - `cpu_millicores` integer
    - `created_at` string
    - `created_by` string
    - `dataplane_url` string
    - `delete_after_stop_seconds` integer
    - `fs_capacity_bytes` integer
    - `id` string
    - `idle_ttl_seconds` integer
    - `labels` SandboxesLabels
    - `mem_bytes` integer
    - `mount_config` SandboxesSandboxMountConfig (unresolved $ref)
    - `name` string
    - `persistent` boolean: Persistent (private beta) reports whether the sandbox keeps its filesystem across stops. When false, its writes are discarded whenever it stops and it is not charged for storage.
    - `preserve_memory_on_stop` boolean
    - `proxy_config` SandboxesProxyConfig
      - `access_control` SandboxesAccessControl
        - `allow_list` string[]
        - `deny_list` string[]
      - `callbacks` SandboxesCallback[]
        - `full_request` boolean
        - `match_hosts` string[], required
        - `request_headers` SandboxesProxyHeader[]
          - `is_set` boolean
          - `name` string, required
          - `type` 'plaintext' | 'opaque' | 'workspace_secret', required
          - `value` string
        - `ttl_seconds` integer, required
        - `url` string, required
      - `description` string: Description says what this configuration as a whole lets the sandbox reach, complementing the per-rule descriptions. At most 1024 characters.
      - `no_proxy` string[]
      - `rules` SandboxesProxyRule[] (unresolved $ref)
    - `run_config` SandboxapiRunConfig
      - `env_vars` object
      - `user` string
      - `work_dir` string
    - `size_class` string
    - `snapshot_id` string
    - `status` string
    - `status_message` string
    - `stopped_at` string
    - `updated_at` string
    - `updated_by` string
    - `vcpus` integer
    - `volumes` SandboxesSandboxVolumeResponse[]: Volumes (beta) are the volumes attached to the sandbox, in slot order. Absent when the workspace does not have sandbox volumes enabled.
      - `mount_path` string
      - `read_only` boolean
      - `volume_id` string
      - `volume_name` string
  - `next_cursor` string: Cursor for the next page, or null on the last page. A non-null value is the only signal that more pages exist. Treat it as opaque.
  - `offset` integer: Deprecated: use next_cursor. Offset to request for the next page, or 0 when no pages remain.
  - `sandboxes` SandboxesSandboxResponse[]: Deprecated: use items. Duplicates items.
    - `access_delegation` SandboxesAccessDelegation
      - `mode` 'INHERIT' | 'EXPLICIT', required
      - `permissions` string[]
    - `cpu_millicores` integer
    - `created_at` string
    - `created_by` string
    - `dataplane_url` string
    - `delete_after_stop_seconds` integer
    - `fs_capacity_bytes` integer
    - `id` string
    - `idle_ttl_seconds` integer
    - `labels` SandboxesLabels
    - `mem_bytes` integer
    - `mount_config` SandboxesSandboxMountConfig (unresolved $ref)
    - `name` string
    - `persistent` boolean: Persistent (private beta) reports whether the sandbox keeps its filesystem across stops. When false, its writes are discarded whenever it stops and it is not charged for storage.
    - `preserve_memory_on_stop` boolean
    - `proxy_config` SandboxesProxyConfig
      - `access_control` SandboxesAccessControl
        - `allow_list` string[]
        - `deny_list` string[]
      - `callbacks` SandboxesCallback[]
        - `full_request` boolean
        - `match_hosts` string[], required
        - `request_headers` SandboxesProxyHeader[]
          - `is_set` boolean
          - `name` string, required
          - `type` 'plaintext' | 'opaque' | 'workspace_secret', required
          - `value` string
        - `ttl_seconds` integer, required
        - `url` string, required
      - `description` string: Description says what this configuration as a whole lets the sandbox reach, complementing the per-rule descriptions. At most 1024 characters.
      - `no_proxy` string[]
      - `rules` SandboxesProxyRule[] (unresolved $ref)
    - `run_config` SandboxapiRunConfig
      - `env_vars` object
      - `user` string
      - `work_dir` string
    - `size_class` string
    - `snapshot_id` string
    - `status` string
    - `status_message` string
    - `stopped_at` string
    - `updated_at` string
    - `updated_by` string
    - `vcpus` integer
    - `volumes` SandboxesSandboxVolumeResponse[]: Volumes (beta) are the volumes attached to the sandbox, in slot order. Absent when the workspace does not have sandbox volumes enabled.
      - `mount_path` string
      - `read_only` boolean
      - `volume_id` string
      - `volume_name` string

## Other responses

- `400`: invalid page_size, cursor, or sort_order, or a deprecated parameter combined with its replacement
- `403`: Forbidden
- `422`: invalid limit or offset
- `500`: Internal Server Error

## Changes

- **2026-10-26** `dfe647d1748e`: 6 info
  - added the optional property `items/items/persistent` to the response with the `200` status
  - added the optional property `items/items/proxy_config/rules/items/relay_id` to the response with the `200` status
  - added the optional property `items/items/volumes` to the response with the `200` status
  - added the optional property `sandboxes/items/persistent` to the response with the `200` status
  - …2 more
- **2026-10-16** `1a8ee9358d81`: 1 info
  - endpoint added

[Operation history](https://skmtc.dev/langchain-ai/apis/langsmith/changes/api/v2/sandboxes/boxes/get.md)

---

[API](https://skmtc.dev/langchain-ai/apis/langsmith.md) - [All operations](https://skmtc.dev/langchain-ai/apis/langsmith/llms.txt) - [OpenAPI document](https://skmtc.dev/langchain-ai/apis/langsmith/revisions/7a01c01f75e8?raw)