# Volumes ## Create `gpu_droplets.volumes.create(VolumeCreateParams**kwargs) -> VolumeCreateResponse` **post** `/v2/volumes` To create a new volume, send a POST request to `/v2/volumes`. Optionally, a `filesystem_type` attribute may be provided in order to automatically format the volume's filesystem. Pre-formatted volumes are automatically mounted when attached to Ubuntu, Debian, Fedora, Fedora Atomic, and CentOS Droplets created on or after April 26, 2018. Attaching pre-formatted volumes to Droplets without support for auto-mounting is not recommended. ### Parameters - **name:** `str` A human-readable name for the block storage volume. Must be lowercase and be composed only of numbers, letters and "-", up to a limit of 64 characters. The name must begin with a letter. - **region:** `Literal["ams1", "ams2", "ams3", 12 more]` The slug identifier for the region where the resource will initially be available. - `"ams1"` - `"ams2"` - `"ams3"` - `"blr1"` - `"fra1"` - `"lon1"` - `"nyc1"` - `"nyc2"` - `"nyc3"` - `"sfo1"` - `"sfo2"` - `"sfo3"` - `"sgp1"` - `"tor1"` - `"syd1"` - **size\_gigabytes:** `int` The size of the block storage volume in GiB (1024^3). This field does not apply when creating a volume from a snapshot. - **description:** `str` An optional free-form text field to describe a block storage volume. - **filesystem\_label:** `str` The label applied to the filesystem. Labels for ext4 type filesystems may contain 16 characters while labels for xfs type filesystems are limited to 12 characters. May only be used in conjunction with filesystem_type. - **filesystem\_type:** `str` The name of the filesystem type to be used on the volume. When provided, the volume will automatically be formatted to the specified filesystem type. Currently, the available options are `ext4` and `xfs`. Pre-formatted volumes are automatically mounted when attached to Ubuntu, Debian, Fedora, Fedora Atomic, and CentOS Droplets created on or after April 26, 2018. Attaching pre-formatted volumes to other Droplets is not recommended. - **snapshot\_id:** `str` The unique identifier for the volume snapshot from which to create the volume. - **tags:** `Optional[List[str]]` A flat array of tag names as strings to be applied to the resource. Tag names may be for either existing or new tags.

Requires `tag:create` scope. ### Returns - `class VolumeCreateResponse` - **volume:** `Optional[Volume]` - **id:** `Optional[str]` The unique identifier for the block storage volume. - **created\_at:** `Optional[str]` A time value given in ISO8601 combined date and time format that represents when the block storage volume was created. - **description:** `Optional[str]` An optional free-form text field to describe a block storage volume. - **droplet\_ids:** `Optional[List[int]]` An array containing the IDs of the Droplets the volume is attached to. Note that at this time, a volume can only be attached to a single Droplet. - **filesystem\_label:** `Optional[str]` The label currently applied to the filesystem. - **filesystem\_type:** `Optional[str]` The type of filesystem currently in-use on the volume. - **name:** `Optional[str]` A human-readable name for the block storage volume. Must be lowercase and be composed only of numbers, letters and "-", up to a limit of 64 characters. The name must begin with a letter. - **region:** `Optional[Region]` The region that the block storage volume is located in. When setting a region, the value should be the slug identifier for the region. When you query a block storage volume, the entire region object will be returned. - **size\_gigabytes:** `Optional[int]` The size of the block storage volume in GiB (1024^3). This field does not apply when creating a volume from a snapshot. - **tags:** `Optional[List[str]]` A flat array of tag names as strings applied to the resource.

Requires `tag:read` scope. ### Example ```python from gradient import Gradient client = Gradient() volume = client.gpu_droplets.volumes.create( name="ext4-example", region="nyc1", size_gigabytes=10, description="Block store for examples", filesystem_label="ext4_volume_01", filesystem_type="ext4", ) print(volume.volume) ``` ## Retrieve `gpu_droplets.volumes.retrieve(strvolume_id) -> VolumeRetrieveResponse` **get** `/v2/volumes/{volume_id}` To show information about a block storage volume, send a GET request to `/v2/volumes/$VOLUME_ID`. ### Parameters - **volume\_id:** `str` ### Returns - `class VolumeRetrieveResponse` - **volume:** `Optional[Volume]` - **id:** `Optional[str]` The unique identifier for the block storage volume. - **created\_at:** `Optional[str]` A time value given in ISO8601 combined date and time format that represents when the block storage volume was created. - **description:** `Optional[str]` An optional free-form text field to describe a block storage volume. - **droplet\_ids:** `Optional[List[int]]` An array containing the IDs of the Droplets the volume is attached to. Note that at this time, a volume can only be attached to a single Droplet. - **filesystem\_label:** `Optional[str]` The label currently applied to the filesystem. - **filesystem\_type:** `Optional[str]` The type of filesystem currently in-use on the volume. - **name:** `Optional[str]` A human-readable name for the block storage volume. Must be lowercase and be composed only of numbers, letters and "-", up to a limit of 64 characters. The name must begin with a letter. - **region:** `Optional[Region]` The region that the block storage volume is located in. When setting a region, the value should be the slug identifier for the region. When you query a block storage volume, the entire region object will be returned. - **size\_gigabytes:** `Optional[int]` The size of the block storage volume in GiB (1024^3). This field does not apply when creating a volume from a snapshot. - **tags:** `Optional[List[str]]` A flat array of tag names as strings applied to the resource.

Requires `tag:read` scope. ### Example ```python from gradient import Gradient client = Gradient() volume = client.gpu_droplets.volumes.retrieve( "182bd5e5-6e1a-4fe4-a799-aa6d9a6ab26e", ) print(volume.volume) ``` ## List `gpu_droplets.volumes.list(VolumeListParams**kwargs) -> VolumeListResponse` **get** `/v2/volumes` To list all of the block storage volumes available on your account, send a GET request to `/v2/volumes`. ## Filtering Results ### By Region The `region` may be provided as query parameter in order to restrict results to volumes available in a specific region. For example: `/v2/volumes?region=nyc1` ### By Name It is also possible to list volumes on your account that match a specified name. To do so, send a GET request with the volume's name as a query parameter to `/v2/volumes?name=$VOLUME_NAME`. **Note:** You can only create one volume per region with the same name. ### By Name and Region It is also possible to retrieve information about a block storage volume by name. To do so, send a GET request with the volume's name and the region slug for the region it is located in as query parameters to `/v2/volumes?name=$VOLUME_NAME®ion=nyc1`. ### Parameters - **name:** `str` The block storage volume's name. - **page:** `int` Which 'page' of paginated results to return. - **per\_page:** `int` Number of items returned per page - **region:** `Literal["ams1", "ams2", "ams3", 12 more]` The slug identifier for the region where the resource is available. - `"ams1"` - `"ams2"` - `"ams3"` - `"blr1"` - `"fra1"` - `"lon1"` - `"nyc1"` - `"nyc2"` - `"nyc3"` - `"sfo1"` - `"sfo2"` - `"sfo3"` - `"sgp1"` - `"tor1"` - `"syd1"` ### Returns - `class VolumeListResponse` - **meta:** `MetaProperties` Information about the response itself. - **volumes:** `List[Volume]` Array of volumes. - **id:** `Optional[str]` The unique identifier for the block storage volume. - **created\_at:** `Optional[str]` A time value given in ISO8601 combined date and time format that represents when the block storage volume was created. - **description:** `Optional[str]` An optional free-form text field to describe a block storage volume. - **droplet\_ids:** `Optional[List[int]]` An array containing the IDs of the Droplets the volume is attached to. Note that at this time, a volume can only be attached to a single Droplet. - **filesystem\_label:** `Optional[str]` The label currently applied to the filesystem. - **filesystem\_type:** `Optional[str]` The type of filesystem currently in-use on the volume. - **name:** `Optional[str]` A human-readable name for the block storage volume. Must be lowercase and be composed only of numbers, letters and "-", up to a limit of 64 characters. The name must begin with a letter. - **region:** `Optional[Region]` The region that the block storage volume is located in. When setting a region, the value should be the slug identifier for the region. When you query a block storage volume, the entire region object will be returned. - **size\_gigabytes:** `Optional[int]` The size of the block storage volume in GiB (1024^3). This field does not apply when creating a volume from a snapshot. - **tags:** `Optional[List[str]]` A flat array of tag names as strings applied to the resource.

Requires `tag:read` scope. - **links:** `Optional[PageLinks]` ### Example ```python from gradient import Gradient client = Gradient() volumes = client.gpu_droplets.volumes.list() print(volumes.meta) ``` ## Delete `gpu_droplets.volumes.delete(strvolume_id)` **delete** `/v2/volumes/{volume_id}` To delete a block storage volume, destroying all data and removing it from your account, send a DELETE request to `/v2/volumes/$VOLUME_ID`. No response body will be sent back, but the response code will indicate success. Specifically, the response code will be a 204, which means that the action was successful with no returned body data. ### Parameters - **volume\_id:** `str` ### Example ```python from gradient import Gradient client = Gradient() client.gpu_droplets.volumes.delete( "182bd5e5-6e1a-4fe4-a799-aa6d9a6ab26e", ) ``` ## Delete By Name `gpu_droplets.volumes.delete_by_name(VolumeDeleteByNameParams**kwargs)` **delete** `/v2/volumes` Block storage volumes may also be deleted by name by sending a DELETE request with the volume's **name** and the **region slug** for the region it is located in as query parameters to `/v2/volumes?name=$VOLUME_NAME®ion=nyc1`. No response body will be sent back, but the response code will indicate success. Specifically, the response code will be a 204, which means that the action was successful with no returned body data. ### Parameters - **name:** `str` The block storage volume's name. - **region:** `Literal["ams1", "ams2", "ams3", 12 more]` The slug identifier for the region where the resource is available. - `"ams1"` - `"ams2"` - `"ams3"` - `"blr1"` - `"fra1"` - `"lon1"` - `"nyc1"` - `"nyc2"` - `"nyc3"` - `"sfo1"` - `"sfo2"` - `"sfo3"` - `"sgp1"` - `"tor1"` - `"syd1"` ### Example ```python from gradient import Gradient client = Gradient() client.gpu_droplets.volumes.delete_by_name() ```