> ## 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 and Delete Volumes

> Enumerate your Declaw volumes, inspect metadata, and delete the ones you no longer need.

## What You'll Learn

* Listing every volume owned by the caller
* Inspecting per-volume metadata (size, content type, creation time)
* Deleting a single volume (blob + metadata row)

## Prerequisites

<Snippet file="snippets/env-setup.mdx" />

## Listing

<CodeGroup>
  ```python Python theme={null}
  from declaw import Volumes

  volumes = Volumes.list()  # newest first
  for vol in volumes:
      print(f"{vol.volume_id}  {vol.name:30s}  {vol.size_bytes:>12,} bytes  {vol.created_at}")
  ```

  ```typescript TypeScript theme={null}
  import { Volumes } from '@declaw/sdk';

  const volumes = await Volumes.list(); // newest first
  for (const vol of volumes) {
    console.log(
      `${vol.volumeId}  ${vol.name.padEnd(30)}  ${vol.sizeBytes} bytes  ${vol.createdAt}`,
    );
  }
  ```
</CodeGroup>

Returns an empty list if the caller has no volumes. The list is owner-scoped: another tenant's volumes are never visible.

## Fetching One

<CodeGroup>
  ```python Python theme={null}
  vol = Volumes.get("vol-abc123")
  print(vol.blob_key)       # object-store key, for reference only
  print(vol.size_bytes)
  ```

  ```typescript TypeScript theme={null}
  const vol = await Volumes.get('vol-abc123');
  console.log(vol.blobKey);
  console.log(vol.sizeBytes);
  ```
</CodeGroup>

Raises `NotFoundException` (Python) / `NotFoundError` (TypeScript) on an unknown or non-owned volume ID.

## Deleting

<CodeGroup>
  ```python Python theme={null}
  Volumes.delete("vol-abc123")
  ```

  ```typescript TypeScript theme={null}
  await Volumes.delete('vol-abc123');
  ```
</CodeGroup>

Deletion removes both the blob and the catalog row. It does **not** affect sandboxes that were previously created with the volume — they hold their own hydrated copies in their overlays. Future `Sandbox.create(volumes=[...])` calls referencing that `volume_id` will fail with 403.

## Housekeeping Pattern

Delete every volume whose name matches a prefix and was created more than 7 days ago:

```python theme={null}
import datetime as dt
from declaw import Volumes

cutoff = dt.datetime.now(dt.timezone.utc) - dt.timedelta(days=7)

for vol in Volumes.list():
    created = dt.datetime.fromisoformat(vol.created_at.rstrip("Z") + "+00:00")
    if vol.name.startswith("ephemeral-") and created < cutoff:
        print(f"deleting {vol.volume_id} ({vol.name}, {vol.size_bytes} bytes)")
        Volumes.delete(vol.volume_id)
```

## Limitations

* There is no bulk-delete endpoint; loop over `Volumes.list()` and call `.delete()` per item.
* Deletion is not transactional with in-flight `Sandbox.create` calls. A volume referenced by a not-yet-dispatched create can be deleted between validation and dispatch; the create then fails.