# Actions ## Retrieve `gpu_droplets.actions.retrieve(intaction_id, ActionRetrieveParams**kwargs) -> ActionRetrieveResponse` **get** `/v2/droplets/{droplet_id}/actions/{action_id}` To retrieve a Droplet action, send a GET request to `/v2/droplets/$DROPLET_ID/actions/$ACTION_ID`. The response will be a JSON object with a key called `action`. The value will be a Droplet action object. ### Parameters - **droplet\_id:** `int` - **action\_id:** `int` ### Returns - `class ActionRetrieveResponse` - **action:** `Optional[Action]` ### Example ```python from gradient import Gradient client = Gradient() action = client.gpu_droplets.actions.retrieve( action_id=36804636, droplet_id=3164444, ) print(action.action) ``` ## List `gpu_droplets.actions.list(intdroplet_id, ActionListParams**kwargs) -> ActionListResponse` **get** `/v2/droplets/{droplet_id}/actions` To retrieve a list of all actions that have been executed for a Droplet, send a GET request to `/v2/droplets/$DROPLET_ID/actions`. The results will be returned as a JSON object with an `actions` key. This will be set to an array filled with `action` objects containing the standard `action` attributes. ### Parameters - **droplet\_id:** `int` - **page:** `int` Which 'page' of paginated results to return. - **per\_page:** `int` Number of items returned per page ### Returns - `class ActionListResponse` - **meta:** `MetaProperties` Information about the response itself. - **actions:** `Optional[List[Action]]` - **id:** `Optional[int]` A unique numeric ID that can be used to identify and reference an action. - **completed\_at:** `Optional[datetime]` A time value given in ISO8601 combined date and time format that represents when the action was completed. - **region:** `Optional[Region]` - **region\_slug:** `Optional[str]` A human-readable string that is used as a unique identifier for each region. - **resource\_id:** `Optional[int]` A unique identifier for the resource that the action is associated with. - **resource\_type:** `Optional[str]` The type of resource that the action is associated with. - **started\_at:** `Optional[datetime]` A time value given in ISO8601 combined date and time format that represents when the action was initiated. - **status:** `Optional[Literal["in-progress", "completed", "errored"]]` The current status of the action. This can be "in-progress", "completed", or "errored". - `"in-progress"` - `"completed"` - `"errored"` - **type:** `Optional[str]` This is the type of action that the object represents. For example, this could be "transfer" to represent the state of an image transfer action. - **links:** `Optional[PageLinks]` ### Example ```python from gradient import Gradient client = Gradient() actions = client.gpu_droplets.actions.list( droplet_id=3164444, ) print(actions.meta) ``` ## Bulk Initiate `gpu_droplets.actions.bulk_initiate(ActionBulkInitiateParams**kwargs) -> ActionBulkInitiateResponse` **post** `/v2/droplets/actions` Some actions can be performed in bulk on tagged Droplets. The actions can be initiated by sending a POST to `/v2/droplets/actions?tag_name=$TAG_NAME` with the action arguments. Only a sub-set of action types are supported: - `power_cycle` - `power_on` - `power_off` - `shutdown` - `enable_ipv6` - `enable_backups` - `disable_backups` - `snapshot` (also requires `image:create` permission) ### Parameters - **type:** `Literal["enable_backups", "disable_backups", "reboot", 12 more]` The type of action to initiate for the Droplet. - `"enable_backups"` - `"disable_backups"` - `"reboot"` - `"power_cycle"` - `"shutdown"` - `"power_off"` - `"power_on"` - `"restore"` - `"password_reset"` - `"resize"` - `"rebuild"` - `"rename"` - `"change_kernel"` - `"enable_ipv6"` - `"snapshot"` - **tag\_name:** `str` Used to filter Droplets by a specific tag. Can not be combined with `name` or `type`.
Requires `tag:read` scope. ### Returns - `class ActionBulkInitiateResponse` - **actions:** `Optional[List[Action]]` - **id:** `Optional[int]` A unique numeric ID that can be used to identify and reference an action. - **completed\_at:** `Optional[datetime]` A time value given in ISO8601 combined date and time format that represents when the action was completed. - **region:** `Optional[Region]` - **region\_slug:** `Optional[str]` A human-readable string that is used as a unique identifier for each region. - **resource\_id:** `Optional[int]` A unique identifier for the resource that the action is associated with. - **resource\_type:** `Optional[str]` The type of resource that the action is associated with. - **started\_at:** `Optional[datetime]` A time value given in ISO8601 combined date and time format that represents when the action was initiated. - **status:** `Optional[Literal["in-progress", "completed", "errored"]]` The current status of the action. This can be "in-progress", "completed", or "errored". - `"in-progress"` - `"completed"` - `"errored"` - **type:** `Optional[str]` This is the type of action that the object represents. For example, this could be "transfer" to represent the state of an image transfer action. ### Example ```python from gradient import Gradient client = Gradient() response = client.gpu_droplets.actions.bulk_initiate( type="reboot", ) print(response.actions) ``` ## Initiate `gpu_droplets.actions.initiate(intdroplet_id, ActionInitiateParams**kwargs) -> ActionInitiateResponse` **post** `/v2/droplets/{droplet_id}/actions` To initiate an action on a Droplet send a POST request to `/v2/droplets/$DROPLET_ID/actions`. In the JSON body to the request, set the `type` attribute to on of the supported action types: | Action | Details | Additionally Required Permission | | ----------------------------------- | ----------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------- | -------------------------------- | | `enable_backups` | Enables backups for a Droplet | | | `disable_backups` | Disables backups for a Droplet | | | `change_backup_policy` | Update the backup policy for a Droplet | | | `reboot` | Reboots a Droplet. A `reboot` action is an attempt to reboot the Droplet in a graceful way, similar to using the `reboot` command from the console. | | | `power_cycle` | Power cycles a Droplet. A `powercycle` action is similar to pushing the reset button on a physical machine, it's similar to booting from scratch. | | | `shutdown` | Shutsdown a Droplet. A shutdown action is an attempt to shutdown the Droplet in a graceful way, similar to using the `shutdown` command from the console. Since a `shutdown` command can fail, this action guarantees that the command is issued, not that it succeeds. The preferred way to turn off a Droplet is to attempt a shutdown, with a reasonable timeout, followed by a `power_off` action to ensure the Droplet is off. | | | `power_off` | Powers off a Droplet. A `power_off` event is a hard shutdown and should only be used if the `shutdown` action is not successful. It is similar to cutting the power on a server and could lead to complications. | | | `power_on` | Powers on a Droplet. | | | `restore` | Restore a Droplet using a backup image. The image ID that is passed in must be a backup of the current Droplet instance. The operation will leave any embedded SSH keys intact. | droplet:admin | | `password_reset` | Resets the root password for a Droplet. A new password will be provided via email. It must be changed after first use. | droplet:admin | | `resize` | Resizes a Droplet. Set the `size` attribute to a size slug. If a permanent resize with disk changes included is desired, set the `disk` attribute to `true`. | droplet:create | | `rebuild` | Rebuilds a Droplet from a new base image. Set the `image` attribute to an image ID or slug. | droplet:admin | | `rename` | Renames a Droplet. | | | `change_kernel` | Changes a Droplet's kernel. Only applies to Droplets with externally managed kernels. All Droplets created after March 2017 use internal kernels by default. | | | `enable_ipv6` | Enables IPv6 for a Droplet. Once enabled for a Droplet, IPv6 can not be disabled. When enabling IPv6 on an existing Droplet, [additional OS-level configuration](https://docs.digitalocean.com/products/networking/ipv6/how-to/enable/#on-existing-droplets) is required. | | | `snapshot` | Takes a snapshot of a Droplet. | image:create | ### Parameters - **droplet\_id:** `int` - **type:** `Literal["enable_backups", "disable_backups", "reboot", 12 more]` The type of action to initiate for the Droplet. - `"enable_backups"` - `"disable_backups"` - `"reboot"` - `"power_cycle"` - `"shutdown"` - `"power_off"` - `"power_on"` - `"restore"` - `"password_reset"` - `"resize"` - `"rebuild"` - `"rename"` - `"change_kernel"` - `"enable_ipv6"` - `"snapshot"` ### Returns - `class ActionInitiateResponse` - **action:** `Optional[Action]` ### Example ```python from gradient import Gradient client = Gradient() response = client.gpu_droplets.actions.initiate( droplet_id=3164444, type="reboot", ) print(response.action) ```