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

# List drives

`GET /drives`

Returns all drives in the workspace. Drives provide persistent storage that can be attached to agents, functions, and sandboxes. Starting with API version 2026-04-28, the response wraps items in `{data, meta}` and supports cursor pagination via the `cursor` and `limit` query parameters; older versions keep returning a bare array with all drives.

## 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

- DriveList — Cursor-paginated list of drives. Returned starting with API version 2026-04-28; older API versions return a bare array.
  - `data` Drive[] — Page of drives.
    - `events` CoreEvent[] — Events happening on a resource deployed on Blaxel
      - `canaryRevision` string — Canary revisionID link to the event
      - `message` string — Event message
      - `revision` string — RevisionID link to the event
      - `status` string — Event status
      - `time` string — Event time
      - `type` string — Event type
    - `metadata` Metadata, required — Owner fields for Persistence
      - `createdAt` string — The date and time when the resource was created
      - `updatedAt` string — The date and time when the resource was updated
      - `createdBy` string — The user or service account who created the resource
      - `updatedBy` string — The user or service account who updated the resource
      - `displayName` string — Human-readable name for display in the UI. Can contain spaces and special characters, max 63 characters.
      - `externalId` string — Caller-owned identifier for external lookups. Max 64 chars, alphanumeric + dash.
      - `labels` MetadataLabels — Key-value pairs for organizing and filtering resources. Labels can be used to categorize resources by environment, project, team, or any custom taxonomy.
      - `name` string, required — Unique identifier for the resource within the workspace. Must be lowercase alphanumeric with hyphens, max 49 characters. Immutable after creation.
      - `plan` string — Billing plan tier applied to this resource (inherited from workspace account)
      - `url` string — Auto-generated endpoint URL for accessing this resource (for agents, functions, models, sandboxes)
      - `workspace` string — Name of the workspace this resource belongs to (read-only, set automatically)
    - `spec` DriveSpec, required — Immutable drive configuration set at creation time
      - `infrastructureId` string — The internal infrastructure resource identifier for this drive (bucket name)
      - `permissions` DrivePermission[] — Permissions controlling which workloads can access this drive. Empty means all workloads in the workspace can access the drive. Maximum 3 permissions.
        - `labels` object — Labels that the workload must have. All labels must match (AND logic). Empty labels match all workloads.
        - `mode` 'read' | 'read-write' — Access mode granted by this permission
        - `path` string — Subfolder path to restrict access to. Defaults to / (full drive).
      - `region` string — Deployment region for the drive (e.g., us-pdx-1, eu-lon-1). Must match the region of resources it attaches to.
      - `size` integer — Optional size limit for the drive in GB. If not specified, drive has no size limit.
    - `state` DriveState — Current runtime state of the drive
      - `s3Url` string — S3-compatible endpoint URL for accessing drive contents
    - `status` string — Drive status computed from events
  - `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

---

[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/revisions/dfa264bc72ee/schema)