> ## Documentation Index > Fetch the complete documentation index at: https://docs.baseten.co/llms.txt > Use this file to discover all available pages before exploring further. # List volumes > Returns one row per volume in the namespace, each with its tags, head version, and version counts. ## OpenAPI ````yaml get /v1/volumes openapi: 3.1.0 info: description: REST API for management of Baseten resources title: Baseten management API version: 1.0.0 servers: - url: https://api.baseten.co security: - BearerAuth: [] paths: /v1/volumes: get: summary: Gets the volumes in a namespace description: >- Returns one row per volume in the namespace, each with its tags, head version, version counts, and any scheduled expiry. Pass namespace to choose the namespace, which is required because the volume service has no cross-namespace inventory. Versions live on the versions sub-resource, so this response stays a fixed size per volume no matter how long a volume's history is. A volume with no live versions left, whether deleted or expired, is not listed. parameters: - name: cursor in: query required: false description: >- Opaque cursor returned by a previous page. Omit to fetch the first page. schema: anyOf: - type: string - type: 'null' default: null title: Cursor - name: limit in: query required: false description: Maximum number of volumes to return. schema: default: 100 maximum: 1000 minimum: 1 title: Limit type: integer - name: namespace in: query required: true description: >- Namespace to list volumes in. Required, because the volume service has no cross-namespace inventory. schema: title: Namespace type: string responses: '200': description: '' content: application/json: schema: $ref: '#/components/schemas/ListVolumesResponseV1' x-codeSamples: - lang: bash source: | curl --request GET \ --url https://api.baseten.co/v1/volumes \ --header "Authorization: Bearer $BASETEN_API_KEY" - lang: python source: |- import requests import os API_KEY = os.environ.get("BASETEN_API_KEY", "") url = "https://api.baseten.co/v1/volumes" headers = {"Authorization": f"Bearer {API_KEY}"} response = requests.request( "GET", url, headers=headers, params={'cursor': None, 'namespace': None} ) print(response.text) components: schemas: ListVolumesResponseV1: description: A page of volumes in one namespace. properties: items: description: Items in this page. items: $ref: '#/components/schemas/VolumeV1' title: Items type: array pagination: $ref: '#/components/schemas/PaginationResponseV1' description: Pagination metadata for the page. required: - items - pagination title: ListVolumesResponseV1 type: object VolumeV1: properties: namespace: description: Namespace the volume belongs to, in lowercase. title: Namespace type: string name: description: Name of the volume, in lowercase. title: Name type: string version_ref: description: >- Full address of the volume, as `bdn:/`. Paste this into the `bdn.mounts` section of a config.yaml. title: Version Ref type: string sequence: description: >- Revision counter for the volume, incremented on every commit, tag change, delete, and restore. A tag or version that expires leaves without changing it; the next write then increments it once. Use it to detect that a volume was written to. title: Sequence type: integer updated_at: description: >- When the volume was last written to, in ISO 8601 format. An expiry does not update it. format: date-time title: Updated At type: string expires_at: anyOf: - format: date-time type: string - type: 'null' description: >- When the whole volume expires, in ISO 8601 format. At that instant every live version is deleted, every tag drops, and the volume leaves the volume listing; each version then stays restorable until its recovery deadline passes. Null for a volume that never expires. title: Expires At head: anyOf: - $ref: '#/components/schemas/VolumeVersionSummaryV1' - type: 'null' description: >- Version that the reserved `head` tag points at, which a reference with no tag or digest resolves to. Never an expiring version. Null when the volume has no head, or when your API key cannot read it. tags: description: >- Tags on the volume that your API key can read. A tag with `expires_at` leaves this list at that instant. items: $ref: '#/components/schemas/VolumeTagV1' title: Tags type: array tag_count: description: >- Total number of tags on the volume, which can exceed the length of `tags` when your API key cannot read all of them. Counts only tags that have not expired. title: Tag Count type: integer versions_alive: description: Number of versions that have not been deleted or expired. title: Versions Alive type: integer versions_tombstoned: description: >- Number of versions that have been deleted or expired and are still within their recovery window. title: Versions Tombstoned type: integer versions_untagged: description: Number of live versions that no tag points at. title: Versions Untagged type: integer versions_expiring: description: >- Number of live versions with an expiry still ahead of them. A version that has already expired counts in `versions_tombstoned` instead. title: Versions Expiring type: integer versions_earliest_expires_at: anyOf: - format: date-time type: string - type: 'null' description: >- Earliest expiry among the live versions, in ISO 8601 format. Null when no live version is scheduled to expire. title: Versions Earliest Expires At required: - namespace - name - version_ref - sequence - updated_at - expires_at - head - tags - tag_count - versions_alive - versions_tombstoned - versions_untagged - versions_expiring - versions_earliest_expires_at title: VolumeV1 type: object PaginationResponseV1: properties: has_more: description: Whether more items exist after this page. title: Has More type: boolean cursor: anyOf: - type: string - type: 'null' default: null description: >- Opaque cursor to pass into the next request. Null when there is no next page. title: Cursor required: - has_more title: PaginationResponseV1 type: object VolumeVersionSummaryV1: properties: digest: description: Content digest of the version, as `b3:`. title: Digest type: string total_size_bytes: description: Total size of the version's files in bytes. title: Total Size Bytes type: integer created_at: description: When the version was committed, in ISO 8601 format. format: date-time title: Created At type: string required: - digest - total_size_bytes - created_at title: VolumeVersionSummaryV1 type: object VolumeTagV1: properties: name: description: Tag name. Tags are case-sensitive. title: Name type: string digest: description: Digest of the version the tag points at, as `b3:`. title: Digest type: string expires_at: anyOf: - format: date-time type: string - type: 'null' description: >- When the tag stops resolving and leaves the volume, in ISO 8601 format. Null for a tag that never expires. The version it points at is not affected. title: Expires At required: - name - digest - expires_at title: VolumeTagV1 type: object securitySchemes: BearerAuth: type: http scheme: bearer description: >- Send `Authorization: Bearer `. The legacy `Authorization: Api-Key ` scheme is also accepted. ````