---
title: "List persistent volumes"
method: GET
path: "/volumes"
tags: ["volumes"]
---

# List persistent volumes

`GET /volumes`

Returns persistent storage volumes in the workspace. Volumes can be attached to sandboxes for durable file storage that persists across sessions and sandbox deletions. Starting with API version 2026-04-28 the response is wrapped in `{data, meta}` and supports cursor pagination via the `cursor` and `limit` query parameters; older versions keep returning a bare array of volumes.

## Query parameters

- `cursor` string
- `limit` integer
- `sort` 'createdAt:desc' | 'createdAt:asc' | 'name:asc' | 'name:desc'
- `q` string
- `anchor` 'end'
- `externalId` string

## Response `200`

successful operation

- VolumeList — Cursor-paginated list of volumes. Returned starting with API version 2026-04-28; older API versions return a bare array. Items use the lite shape (no inline event history).
  - `data` LiteVolume[] — Page of volumes.
    - `metadata` LiteVolumeMetadata — Compact metadata for a Volume, returned in listing responses.
      - `createdAt` string
      - `displayName` string
      - `externalId` string — Caller-owned identifier for external lookups.
      - `name` string
      - `updatedAt` string
    - `spec` LiteVolumeSpec — Compact spec for a Volume, returned in listing responses.
      - `region` string — Region the volume is provisioned in.
      - `size` integer — Volume size in gigabytes.
    - `state` VolumeState — Current runtime state of the volume including attachment status
      - `attachedTo` string — Resource currently using this volume in format "type:name" (e.g., "sandbox:my-sandbox"). Empty if not attached.
    - `status` string — Computed status of the volume.
    - `terminatedAt` string — Termination timestamp for soft-deleted volumes.
  - `meta` PaginationMeta — Pagination metadata returned alongside a page of listing results. Always present on listing endpoints starting with API version 2026-04-28.
    - `hasMore` boolean — True when more pages are available beyond the current one.
    - `nextCursor` string — Opaque cursor to pass back as the `cursor` query param for the next page. Empty when there are no more pages.
    - `total` integer — Total number of items in the workspace, ignoring the current page's filters. Lets the UI render "page X of Y" without walking the cursor chain. Computed from the hash-only metadata.workspace GSI count, so search (`q`) does not narrow it.

## Other responses

- `401` — Unauthorized - Invalid or missing authentication credentials
- `403` — Forbidden - Insufficient permissions to list volumes
- `500` — Internal server error

---

[API](https://skmtc.net/blaxel/apis/blaxel-control-plane.md) · [All operations](https://skmtc.net/blaxel/apis/blaxel-control-plane/llms.txt) · [OpenAPI document](https://skmtc-service-staging.skmtc.workers.dev/v1/apis/blaxel/blaxel-control-plane/versions/dfa264bc72ee/schema)