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

# List Sandboxes

> List sandboxes visible to the caller

## Query Parameters

<ParamField query="status" type="string">
  Filter by status.
</ParamField>

<ParamField query="tag" type="string">
  Filter by tag. Repeat `tag` to match multiple tags.
</ParamField>

<ParamField query="template" type="string">
  Filter by template, such as `base-ubuntu` or `desktop-ubuntu`.
</ParamField>

<ParamField query="exclude_template" type="string">
  Exclude a template from results.
</ParamField>

<ParamField query="limit" type="number" default="500">
  Page size. Use `cursor` to continue. The SDK can auto-page when you need the full list.
</ParamField>

<ParamField query="cursor" type="string">
  Cursor from the previous response.
</ParamField>

<ParamField query="all" type="boolean">
  Admin-only: include all organization sandboxes instead of only caller-visible rows.
</ParamField>

By default the API returns active lifecycle states, not destroyed/orphaned history.

## Response

<ResponseField name="data" type="array">
  Sandbox summaries.
</ResponseField>

<ResponseField name="meta.hasMore" type="boolean">
  Whether another page is available.
</ResponseField>

<ResponseField name="meta.nextCursor" type="string">
  Cursor for the next page.
</ResponseField>

<RequestExample>
  ```bash cURL theme={null}
  curl "https://api.runtools.ai/v1/sandboxes?status=running&tag=ci&limit=50" \
    -H "X-API-Key: $RUNTOOLS_API_KEY"
  ```

  ```typescript SDK theme={null}
  const allRunning = await rt.sandbox.list({
    status: 'running',
    tags: ['ci'],
  });

  const page = await rt.sandbox.listPage({
    template: 'desktop-ubuntu',
    limit: 25,
  });
  ```
</RequestExample>

<ResponseExample>
  ```json 200 OK theme={null}
  {
    "data": [
      {
        "id": "sandbox-abc123",
        "name": "build-runner",
        "status": "running",
        "template": "base-ubuntu",
        "sshReady": true,
        "vncReady": false,
        "createdAt": "2026-05-06T10:00:00Z"
      }
    ],
    "meta": {
      "hasMore": false,
      "nextCursor": null
    }
  }
  ```
</ResponseExample>