---
title: "GET /v1/volumes — list volumes (API key, org inferred from key)."
method: GET
path: "/v1/volumes"
tags: ["volumes"]
---

# GET /v1/volumes — list volumes (API key, org inferred from key).

`GET /v1/volumes`

List persistent volumes available to the organization, including current usage.

## Response `200`

The org's volumes

- VolumeResponse[]
  - `capacity_bytes` integer, nullable — The volume's configured per-volume storage cap in bytes, or `null` when no cap is set (#496). Derived from the stored `capacity_gib` (the user's configured intent) — the effective ceiling is `min(this, org cap)`.
  - `created_at` string, date-time, required
  - `id` string, uuid, required
  - `kind` 'host' | 'managed', required — What kind of volume this is — its storage source / role. The host volume is the org's single shared "host disk"; managed volumes are user-created, named, platform-provisioned (JuiceFS over our object store). (A future `External` variant — bring-your-own S3/GCS — is intentionally out of scope for now.)
  - `labels` object, required — User-defined labels (empty object when none set).
  - `name` string, nullable — User-facing name. `null` for the host volume (it has no name; it's identified by `kind`).
  - `status` 'active' | 'deleting', required — Lifecycle status of a volume.
  - `storage` 'block', required — How a volume is physically backed — distinct from [`VolumeKind`] (ownership). Every volume is `Block` today; the enum exists so future backings can be added (and reported to the SDK) without another schema change.
  - `updated_at` string, date-time, required
  - `used_bytes` integer, nullable — Bytes currently used under this volume's subtree. `null` when usage is unavailable — the usage service is disabled or unreachable (list degrades gracefully rather than failing) — or on create/delete, which don't sample it.

## Other responses

- `401` — Unauthorized

---

[API](https://skmtc.dev/microsandbox/apis/microsandbox-api.md) · [All operations](https://skmtc.dev/microsandbox/apis/microsandbox-api/llms.txt) · [OpenAPI document](https://skmtc-service-production.skmtc.workers.dev/v1/apis/microsandbox/microsandbox-api/revisions/23f2a45cb09b/schema)