# Actions

## Retrieve

`gpu_droplets.volumes.actions.retrieve(intaction_id, ActionRetrieveParams**kwargs)  -> ActionRetrieveResponse`

**get** `/v2/volumes/{volume_id}/actions/{action_id}`

To retrieve the status of a volume action, send a GET request to `/v2/volumes/$VOLUME_ID/actions/$ACTION_ID`.

### Parameters

- `volume_id: str`

- `action_id: int`

- `page: Optional[int]`

  Which 'page' of paginated results to return.

- `per_page: Optional[int]`

  Number of items returned per page

### Returns

- `class ActionRetrieveResponse: …`

  - `action: Optional[VolumeAction]`

    - `resource_id: Optional[int]`

    - `type: Optional[str]`

      This is the type of action that the object represents. For example, this could be "attach_volume" to represent the state of a volume attach action.

### Example

```python
from gradient import Gradient

client = Gradient()
action = client.gpu_droplets.volumes.actions.retrieve(
    action_id=36804636,
    volume_id="7724db7c-e098-11e5-b522-000f53304e51",
)
print(action.action)
```

## List

`gpu_droplets.volumes.actions.list(strvolume_id, ActionListParams**kwargs)  -> ActionListResponse`

**get** `/v2/volumes/{volume_id}/actions`

To retrieve all actions that have been executed on a volume, send a GET request to `/v2/volumes/$VOLUME_ID/actions`.

### Parameters

- `volume_id: str`

- `page: Optional[int]`

  Which 'page' of paginated results to return.

- `per_page: Optional[int]`

  Number of items returned per page

### Returns

- `class ActionListResponse: …`

  - `meta: MetaProperties`

    Information about the response itself.

    - `total: Optional[int]`

      Number of objects returned by the request.

  - `actions: Optional[List[VolumeAction]]`

    - `resource_id: Optional[int]`

    - `type: Optional[str]`

      This is the type of action that the object represents. For example, this could be "attach_volume" to represent the state of a volume attach action.

  - `links: Optional[PageLinks]`

    - `pages: Optional[Pages]`

      - `class ForwardLinks: …`

        - `last: Optional[str]`

          URI of the last page of the results.

        - `next: Optional[str]`

          URI of the next page of the results.

      - `class BackwardLinks: …`

        - `first: Optional[str]`

          URI of the first page of the results.

        - `prev: Optional[str]`

          URI of the previous page of the results.

      - `PagesUnionMember2 = object`

### Example

```python
from gradient import Gradient

client = Gradient()
actions = client.gpu_droplets.volumes.actions.list(
    volume_id="7724db7c-e098-11e5-b522-000f53304e51",
)
print(actions.meta)
```

## Initiate By ID

`gpu_droplets.volumes.actions.initiate_by_id(strvolume_id, ActionInitiateByIDParams**kwargs)  -> ActionInitiateByIDResponse`

**post** `/v2/volumes/{volume_id}/actions`

To initiate an action on a block storage volume by Id, send a POST request to
`~/v2/volumes/$VOLUME_ID/actions`. The body should contain the appropriate
attributes for the respective action.

## Attach a Block Storage Volume to a Droplet

| Attribute  | Details                                                             |
| ---------- | ------------------------------------------------------------------- |
| type       | This must be `attach`                                               |
| droplet_id | Set to the Droplet's ID                                             |
| region     | Set to the slug representing the region where the volume is located |

Each volume may only be attached to a single Droplet. However, up to fifteen
volumes may be attached to a Droplet at a time. Pre-formatted volumes will be
automatically mounted to Ubuntu, Debian, Fedora, Fedora Atomic, and CentOS
Droplets created on or after April 26, 2018 when attached. On older Droplets,
[additional configuration](https://docs.digitalocean.com/products/volumes/how-to/mount/)
is required.

## Remove a Block Storage Volume from a Droplet

| Attribute  | Details                                                             |
| ---------- | ------------------------------------------------------------------- |
| type       | This must be `detach`                                               |
| droplet_id | Set to the Droplet's ID                                             |
| region     | Set to the slug representing the region where the volume is located |

## Resize a Volume

| Attribute      | Details                                                             |
| -------------- | ------------------------------------------------------------------- |
| type           | This must be `resize`                                               |
| size_gigabytes | The new size of the block storage volume in GiB (1024^3)            |
| region         | Set to the slug representing the region where the volume is located |

Volumes may only be resized upwards. The maximum size for a volume is 16TiB.

### Parameters

- `volume_id: str`

- `droplet_id: int`

  The unique identifier for the Droplet the volume will be attached or detached from.

- `type: Literal["attach", "detach", "resize"]`

  The volume action to initiate.

  - `"attach"`

  - `"detach"`

  - `"resize"`

- `page: Optional[int]`

  Which 'page' of paginated results to return.

- `per_page: Optional[int]`

  Number of items returned per page

- `region: Optional[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"`

- `tags: Optional[SequenceNotStr[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. <br><br>Requires `tag:create` scope.

### Returns

- `class ActionInitiateByIDResponse: …`

  - `action: Optional[VolumeAction]`

    - `resource_id: Optional[int]`

    - `type: Optional[str]`

      This is the type of action that the object represents. For example, this could be "attach_volume" to represent the state of a volume attach action.

### Example

```python
from gradient import Gradient

client = Gradient()
response = client.gpu_droplets.volumes.actions.initiate_by_id(
    volume_id="7724db7c-e098-11e5-b522-000f53304e51",
    droplet_id=11612190,
    type="attach",
    region="nyc1",
    tags=["aninterestingtag"],
)
print(response.action)
```

## Initiate By Name

`gpu_droplets.volumes.actions.initiate_by_name(ActionInitiateByNameParams**kwargs)  -> ActionInitiateByNameResponse`

**post** `/v2/volumes/actions`

To initiate an action on a block storage volume by Name, send a POST request to
`~/v2/volumes/actions`. The body should contain the appropriate
attributes for the respective action.

## Attach a Block Storage Volume to a Droplet

| Attribute   | Details                                                             |
| ----------- | ------------------------------------------------------------------- |
| type        | This must be `attach`                                               |
| volume_name | The name of the block storage volume                                |
| droplet_id  | Set to the Droplet's ID                                             |
| region      | Set to the slug representing the region where the volume is located |

Each volume may only be attached to a single Droplet. However, up to fifteen
volumes may be attached to a Droplet at a time. Pre-formatted volumes will be
automatically mounted to Ubuntu, Debian, Fedora, Fedora Atomic, and CentOS
Droplets created on or after April 26, 2018 when attached. On older Droplets,
[additional configuration](https://docs.digitalocean.com/products/volumes/how-to/mount/)
is required.

## Remove a Block Storage Volume from a Droplet

| Attribute   | Details                                                             |
| ----------- | ------------------------------------------------------------------- |
| type        | This must be `detach`                                               |
| volume_name | The name of the block storage volume                                |
| droplet_id  | Set to the Droplet's ID                                             |
| region      | Set to the slug representing the region where the volume is located |

### Parameters

- `droplet_id: int`

  The unique identifier for the Droplet the volume will be attached or detached from.

- `type: Literal["attach", "detach", "resize"]`

  The volume action to initiate.

  - `"attach"`

  - `"detach"`

  - `"resize"`

- `page: Optional[int]`

  Which 'page' of paginated results to return.

- `per_page: Optional[int]`

  Number of items returned per page

- `region: Optional[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"`

- `tags: Optional[SequenceNotStr[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. <br><br>Requires `tag:create` scope.

### Returns

- `class ActionInitiateByNameResponse: …`

  - `action: Optional[VolumeAction]`

    - `resource_id: Optional[int]`

    - `type: Optional[str]`

      This is the type of action that the object represents. For example, this could be "attach_volume" to represent the state of a volume attach action.

### Example

```python
from gradient import Gradient

client = Gradient()
response = client.gpu_droplets.volumes.actions.initiate_by_name(
    droplet_id=11612190,
    type="attach",
    region="nyc1",
    tags=["aninterestingtag"],
)
print(response.action)
```

## Domain Types

### Volume Action

- `class VolumeAction: …`

  - `resource_id: Optional[int]`

  - `type: Optional[str]`

    This is the type of action that the object represents. For example, this could be "attach_volume" to represent the state of a volume attach action.