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

# List Sandboxes

> Return all sandboxes visible to the authenticated API key.

Returns all sandboxes owned by the authenticated API key. Killed sandboxes are
hidden by default — pass `?state=all` to include them. Results are wrapped in a
`sandboxes` array with a `next_token` pagination cursor.

## Query Parameters

<ParamField query="limit" type="integer" default="100">
  Maximum number of sandboxes to return. Capped at `1000`.
</ParamField>

<ParamField query="offset" type="integer" default="0">
  Zero-based offset for pagination.
</ParamField>

<ParamField query="state" type="string">
  Pass `"all"` to include killed sandboxes in the results. Any other value (or
  omission) filters them out.
</ParamField>

## Response

<ResponseField name="sandboxes" type="Sandbox[]">
  Array of [Sandbox](/api-reference/sandbox/get) objects. May be empty.
</ResponseField>

<ResponseField name="next_token" type="string | null">
  Pagination cursor for the next page of results. Currently always `null` —
  full pagination is coming in a future release.
</ResponseField>

## Example

<CodeGroup>
  ```bash cURL theme={null}
  curl https://api.declaw.ai/sandboxes \
    -H "X-API-Key: YOUR_API_KEY"
  ```

  ```python Python theme={null}
  from declaw import Sandbox

  sandboxes = Sandbox.list(api_key="YOUR_API_KEY", domain="api.declaw.ai")
  for sbx in sandboxes:
      print(sbx.sandbox_id, sbx.state)
  ```

  ```typescript TypeScript theme={null}
  import { Sandbox } from "@declaw/sdk";

  const sandboxes = await Sandbox.list({
    apiKey: "YOUR_API_KEY",
    domain: "api.declaw.ai",
  });
  for (const sbx of sandboxes) {
    console.log(sbx.sandboxId, sbx.state);
  }
  ```
</CodeGroup>

```json Response theme={null}
{
  "sandboxes": [
    {
      "sandbox_id": "sbx-a1b2c3d4",
      "template_id": "tpl-base",
      "name": "base",
      "state": "running",
      "timeout": 300,
      "started_at": "2024-01-15T10:30:00Z"
    },
    {
      "sandbox_id": "sbx-e5f6g7h8",
      "template_id": "tpl-base",
      "name": "base",
      "state": "paused",
      "timeout": 0,
      "started_at": "2024-01-15T09:00:00Z"
    }
  ],
  "next_token": null
}
```

## Error Responses

| Status | Cause                            |
| ------ | -------------------------------- |
| `401`  | Missing or invalid API key       |
| `500`  | Internal error listing sandboxes |