# Actions ## Retrieve `client.gpuDroplets.actions.retrieve(numberactionID, ActionRetrieveParamsparams, RequestOptionsoptions?): 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 - `actionID: number` - `params: ActionRetrieveParams` - `droplet_id: number` A unique identifier for a Droplet instance. ### Returns - `ActionRetrieveResponse` - `action?: Action` - `id?: number` A unique numeric ID that can be used to identify and reference an action. - `completed_at?: string | null` A time value given in ISO8601 combined date and time format that represents when the action was completed. - `region?: Region` - `available: boolean` This is a boolean value that represents whether new Droplets can be created in this region. - `features: Array` This attribute is set to an array which contains features available in this region - `name: string` The display name of the region. This will be a full name that is used in the control panel and other interfaces. - `sizes: Array` This attribute is set to an array which contains the identifying slugs for the sizes available in this region. sizes:read is required to view. - `slug: string` A human-readable string that is used as a unique identifier for each region. - `region_slug?: string | null` A human-readable string that is used as a unique identifier for each region. - `resource_id?: number | null` A unique identifier for the resource that the action is associated with. - `resource_type?: string` The type of resource that the action is associated with. - `started_at?: string` A time value given in ISO8601 combined date and time format that represents when the action was initiated. - `status?: "in-progress" | "completed" | "errored"` The current status of the action. This can be "in-progress", "completed", or "errored". - `"in-progress"` - `"completed"` - `"errored"` - `type?: string` 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 ```typescript import Gradient from '@digitalocean/gradient'; const client = new Gradient(); const action = await client.gpuDroplets.actions.retrieve(36804636, { droplet_id: 3164444 }); console.log(action.action); ``` ## List `client.gpuDroplets.actions.list(numberdropletID, ActionListParamsquery?, RequestOptionsoptions?): 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 - `dropletID: number` - `query: ActionListParams` - `page?: number` Which 'page' of paginated results to return. - `per_page?: number` Number of items returned per page ### Returns - `ActionListResponse` - `meta: MetaProperties` Information about the response itself. - `total?: number` Number of objects returned by the request. - `actions?: Array` - `id?: number` A unique numeric ID that can be used to identify and reference an action. - `completed_at?: string | null` A time value given in ISO8601 combined date and time format that represents when the action was completed. - `region?: Region` - `available: boolean` This is a boolean value that represents whether new Droplets can be created in this region. - `features: Array` This attribute is set to an array which contains features available in this region - `name: string` The display name of the region. This will be a full name that is used in the control panel and other interfaces. - `sizes: Array` This attribute is set to an array which contains the identifying slugs for the sizes available in this region. sizes:read is required to view. - `slug: string` A human-readable string that is used as a unique identifier for each region. - `region_slug?: string | null` A human-readable string that is used as a unique identifier for each region. - `resource_id?: number | null` A unique identifier for the resource that the action is associated with. - `resource_type?: string` The type of resource that the action is associated with. - `started_at?: string` A time value given in ISO8601 combined date and time format that represents when the action was initiated. - `status?: "in-progress" | "completed" | "errored"` The current status of the action. This can be "in-progress", "completed", or "errored". - `"in-progress"` - `"completed"` - `"errored"` - `type?: string` 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?: PageLinks` - `pages?: ForwardLinks | BackwardLinks | unknown` - `ForwardLinks` - `last?: string` URI of the last page of the results. - `next?: string` URI of the next page of the results. - `BackwardLinks` - `first?: string` URI of the first page of the results. - `prev?: string` URI of the previous page of the results. - `unknown` ### Example ```typescript import Gradient from '@digitalocean/gradient'; const client = new Gradient(); const actions = await client.gpuDroplets.actions.list(3164444); console.log(actions.meta); ``` ## Bulk Initiate `client.gpuDroplets.actions.bulkInitiate(ActionBulkInitiateParamsparams, RequestOptionsoptions?): 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 - `ActionBulkInitiateParams = DropletAction | DropletActionSnapshot` - `ActionBulkInitiateParamsBase` - `type: "enable_backups" | "disable_backups" | "reboot" | 12 more` Body param: 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?: string` Query param: Used to filter Droplets by a specific tag. Can not be combined with `name` or `type`.
Requires `tag:read` scope. - `DropletAction extends ActionBulkInitiateParamsBase` - `DropletActionSnapshot extends ActionBulkInitiateParamsBase` ### Returns - `ActionBulkInitiateResponse` - `actions?: Array` - `id?: number` A unique numeric ID that can be used to identify and reference an action. - `completed_at?: string | null` A time value given in ISO8601 combined date and time format that represents when the action was completed. - `region?: Region` - `available: boolean` This is a boolean value that represents whether new Droplets can be created in this region. - `features: Array` This attribute is set to an array which contains features available in this region - `name: string` The display name of the region. This will be a full name that is used in the control panel and other interfaces. - `sizes: Array` This attribute is set to an array which contains the identifying slugs for the sizes available in this region. sizes:read is required to view. - `slug: string` A human-readable string that is used as a unique identifier for each region. - `region_slug?: string | null` A human-readable string that is used as a unique identifier for each region. - `resource_id?: number | null` A unique identifier for the resource that the action is associated with. - `resource_type?: string` The type of resource that the action is associated with. - `started_at?: string` A time value given in ISO8601 combined date and time format that represents when the action was initiated. - `status?: "in-progress" | "completed" | "errored"` The current status of the action. This can be "in-progress", "completed", or "errored". - `"in-progress"` - `"completed"` - `"errored"` - `type?: string` 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 ```typescript import Gradient from '@digitalocean/gradient'; const client = new Gradient(); const response = await client.gpuDroplets.actions.bulkInitiate({ type: 'reboot' }); console.log(response.actions); ``` ## Initiate `client.gpuDroplets.actions.initiate(numberdropletID, ActionInitiateParamsbody, RequestOptionsoptions?): 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 - `dropletID: number` - `ActionInitiateParams = DropletAction | DropletActionEnableBackups | DropletActionChangeBackupPolicy | 6 more` - `ActionInitiateParamsBase` - `type: "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"` - `DropletAction extends ActionInitiateParamsBase` - `DropletActionEnableBackups extends ActionInitiateParamsBase` - `DropletActionChangeBackupPolicy extends ActionInitiateParamsBase` - `DropletActionRestore extends ActionInitiateParamsBase` - `DropletActionResize extends ActionInitiateParamsBase` - `DropletActionRebuild extends ActionInitiateParamsBase` - `DropletActionRename extends ActionInitiateParamsBase` - `DropletActionChangeKernel extends ActionInitiateParamsBase` - `DropletActionSnapshot extends ActionInitiateParamsBase` ### Returns - `ActionInitiateResponse` - `action?: Action` - `id?: number` A unique numeric ID that can be used to identify and reference an action. - `completed_at?: string | null` A time value given in ISO8601 combined date and time format that represents when the action was completed. - `region?: Region` - `available: boolean` This is a boolean value that represents whether new Droplets can be created in this region. - `features: Array` This attribute is set to an array which contains features available in this region - `name: string` The display name of the region. This will be a full name that is used in the control panel and other interfaces. - `sizes: Array` This attribute is set to an array which contains the identifying slugs for the sizes available in this region. sizes:read is required to view. - `slug: string` A human-readable string that is used as a unique identifier for each region. - `region_slug?: string | null` A human-readable string that is used as a unique identifier for each region. - `resource_id?: number | null` A unique identifier for the resource that the action is associated with. - `resource_type?: string` The type of resource that the action is associated with. - `started_at?: string` A time value given in ISO8601 combined date and time format that represents when the action was initiated. - `status?: "in-progress" | "completed" | "errored"` The current status of the action. This can be "in-progress", "completed", or "errored". - `"in-progress"` - `"completed"` - `"errored"` - `type?: string` 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 ```typescript import Gradient from '@digitalocean/gradient'; const client = new Gradient(); const response = await client.gpuDroplets.actions.initiate(3164444, { type: 'reboot' }); console.log(response.action); ```