# List

Launch stage: GA

`GET /api/2.1/unity-catalog/volumes`

Gets an array of volumes for the current metastore
 under the parent catalog and schema.

 The returned volumes are filtered based on the privileges of the calling user.
 For example, the metastore admin is able to list all the volumes.
 A regular user needs to be the owner or have the **READ VOLUME** privilege
 on the volume to receive the volumes in the response.
 For the latter case, the caller must also be the owner or have the **USE_CATALOG**
 privilege on the parent catalog and the **USE_SCHEMA** privilege on the parent schema.

 There is no guarantee of a specific ordering of the elements in the array.

 PAGINATION BEHAVIOR: The API is by default paginated, a page may contain zero results while still providing a next_page_token.
 Clients must continue reading pages until next_page_token is absent, which is the only indication that the end of results has been reached.

API scopes: unity-catalog

## Query parameters

- `catalog_name` (string, optional)
  The identifier of the catalog
- `schema_name` (string, optional)
  The identifier of the schema
- `include_browse` (boolean, optional)
  Whether to include volumes in the response for which the principal can only access selective metadata for
- `max_results` (int32, optional)
  Maximum number of volumes to return (page length).
  
   If not set, the page length is set to a server configured value (10000, as of 1/29/2024).
   - when set to a value greater than 0, the page length is the minimum of this value and a server configured value (10000, as of 1/29/2024);
   - when set to 0, the page length is set to a server configured value (10000, as of 1/29/2024) (recommended);
   - when set to a value less than 0, an invalid parameter error is returned;
  
   Note: this parameter controls only the maximum number of volumes to return. The actual number of volumes returned in a page
   may be smaller than this value, including 0, even if there are more pages.
  Constraints: `<= 10000`
- `page_token` (string, optional)
  Opaque token returned by a previous request. It must be included in the request to retrieve the next page of results (pagination).

## Returns

Returns a list of VolumeInfo objects.

## Response

```json
{
  "volumes": [
    {
      "name": "string",
      "catalog_name": "string",
      "schema_name": "string",
      "volume_type": "string",
      "storage_location": "string",
      "owner": "string",
      "comment": "string",
      "full_name": "string",
      "volume_id": "string",
      "metastore_id": "string",
      "created_at": 0,
      "created_by": "string",
      "updated_at": 0,
      "updated_by": "string",
      "access_point": "string",
      "browse_only": true
    }
  ],
  "next_page_token": "string"
}
```