> ## Documentation Index > Fetch the complete documentation index at: https://docs.basaltic.sh/llms.txt > Use this file to discover all available pages before exploring further. # List volumes > List volumes owned by the requesting organization in the target region, newest-first. Keyset-paginated by volume id (UUIDv7 sorts by creation time) — pass the last id from the previous page as `marker` to fetch the next. ## OpenAPI ````yaml /api-reference/specs/storage.yaml get /v1/volumes openapi: 3.0.3 info: title: Basaltic Storage API version: 1.0.0 description: | Block volumes with their snapshots and snapshot policies, plus bucket management for object storage. The S3 wire protocol itself is served separately at `objects.{region}.basaltic.cloud`. contact: name: Basaltic Support email: ping@basaltic.sh license: name: Proprietary url: https://basaltic.sh/terms servers: - url: https://storage.{region}.basaltic.sh description: Regional API endpoint variables: region: default: sa-saopaulo-1 description: Region code security: - SignatureAuth: [] paths: /v1/volumes: get: tags: - Storage summary: List volumes description: | List volumes owned by the requesting organization in the target region, newest-first. Keyset-paginated by volume id (UUIDv7 sorts by creation time) — pass the last id from the previous page as `marker` to fetch the next. operationId: listVolumes parameters: - name: limit in: query schema: type: integer minimum: 1 maximum: 500 default: 50 example: 50 - name: marker in: query schema: type: string format: uuid example: 5f8d2c1a-9b3e-4d7a-8c6f-1e2a3b4c5d6e description: Resume token — the last volume id from the previous page. - name: name in: query schema: type: string example: data-vol-01 description: Case-insensitive substring match on the volume name. - name: status in: query schema: $ref: '#/components/schemas/VolumeStatus' responses: '200': description: A page of volumes content: application/json: schema: $ref: '#/components/schemas/VolumeListResponse' '401': $ref: '#/components/responses/Unauthorized' '403': $ref: '#/components/responses/Forbidden' '500': $ref: '#/components/responses/InternalServerError' security: - SignatureAuth: [] components: schemas: VolumeStatus: type: string enum: - creating - available - in_use - extending - deleting - error example: available VolumeListResponse: type: object properties: volumes: type: array items: $ref: '#/components/schemas/Volume' meta: $ref: '#/components/schemas/PaginationMeta' Volume: type: object properties: id: type: string format: uuid readOnly: true example: 5f8d2c1a-9b3e-4d7a-8c6f-1e2a3b4c5d6e crn: type: string readOnly: true description: Cloud Resource Name (name-based, region-scoped). example: crn:storage:sa-saopaulo-1:my-account:volume/data-volume-01 name: type: string maxLength: 128 example: data-vol-01 description: type: string example: Primary data volume for app-01 tags: $ref: '#/components/schemas/Tags' volume_type: $ref: '#/components/schemas/VolumeTypeName' size_gb: type: integer minimum: 1 maximum: 16384 example: 100 status: $ref: '#/components/schemas/VolumeStatus' bootable: type: boolean description: | Set at create time when the volume is provisioned from a bootable image. Immutable after creation. example: false source_image_id: type: string format: uuid nullable: true description: Image the volume was cloned from, when applicable. example: a3c9e7b1-2d4f-4a6b-8e1c-9f0a1b2c3d4e source_snapshot_id: type: string format: uuid nullable: true description: Snapshot the volume was cloned from (restore path), when applicable. example: 019f24a8-4bbe-7441-93af-6bbac0413943 error_message: type: string description: Last failure reason. Empty unless status=error. example: '' created_at: type: string format: date-time readOnly: true example: '2026-01-15T09:30:00Z' updated_at: type: string format: date-time readOnly: true example: '2026-01-15T09:31:12Z' PaginationMeta: type: object properties: total: type: integer description: Total number of items example: 150 limit: type: integer description: Number of items per page example: 20 marker: type: string description: >- Opaque cursor for the next page. Pass it back as the `marker` query parameter; treat it as a token, not a value to parse. example: 550e8400-e29b-41d4-a716-446655440000 has_more: type: boolean description: Whether there are more items example: true Error: type: object required: - error properties: error: type: object required: - code - message - request_id properties: code: type: string description: Error code identifying the type of error example: INVALID_INPUT message: type: string description: Human-readable error message example: Invalid request parameters request_id: type: string format: uuid description: Request ID for debugging example: 550e8400-e29b-41d4-a716-446655440000 Tags: type: object additionalProperties: type: string example: environment: production team: backend VolumeTypeName: type: string enum: - hdd - ssd - nvme description: | Customer-facing storage tier a volume is stored on. Mapped per-region to a Ceph pool by operator config (the mapping is opaque to API callers). example: ssd responses: Unauthorized: description: Authentication required or token invalid content: application/json: schema: $ref: '#/components/schemas/Error' example: error: code: UNAUTHORIZED message: Authentication required request_id: 550e8400-e29b-41d4-a716-446655440000 Forbidden: description: Insufficient permissions content: application/json: schema: $ref: '#/components/schemas/Error' example: error: code: ACCESS_DENIED message: You don't have permission to perform this action request_id: 550e8400-e29b-41d4-a716-446655440000 InternalServerError: description: Internal server error content: application/json: schema: $ref: '#/components/schemas/Error' example: error: code: INTERNAL_ERROR message: An internal error occurred request_id: 550e8400-e29b-41d4-a716-446655440000 securitySchemes: SignatureAuth: type: apiKey in: header name: Authorization description: > Request signing with an access key issued to a service account. An HMAC-SHA256 over a canonical form of the request, close to AWS SigV4. The `basaltic` CLI signs for you. Send `Authorization`, `X-Date` (UTC, `YYYYMMDDTHHMMSSZ`) and `X-Nonce` (random per request); add `X-Content-Sha256` to bind a body, and `X-Amz-Security-Token` when using temporary credentials. ``` Authorization: BASALTIC-HMAC-SHA256 Credential=///basaltic/basaltic_request, SignedHeaders=host;x-date;x-nonce, Signature= ``` `` is the region code you are calling, or `global` for the global services. A signature is valid for 5 minutes from `X-Date`, and mutating requests are replay-guarded on the nonce. **Full signing procedure, including a working implementation:** https://docs.basaltic.sh/authentication ## Rate limits There is no global request budget. A limit applies only where an operation documents a `429`, and that operation says what it counts. Those responses carry `X-RateLimit-Limit`, `X-RateLimit-Remaining`, `X-RateLimit-Reset` and, on a `429`, `Retry-After` — read them rather than hard-coding a number. Retrying before `Retry-After` is refused and extends the window. Everything else is bounded by quota, not by request rate. ````