Droplet Autoscale Pools

Validated on 19 Jun 2018 • Last edited on 23 Mar 2026

View full API reference

Droplet autoscale pools manage automatic horizontal scaling for your applications based on resource usage (CPU, memory, or both) or a static configuration.

Base URL https://api.digitalocean.com

Endpoints

GET List All Autoscale Pools POST Create a New Autoscale Pool GET Retrieve an Existing Autoscale Pool PUT Update Autoscale Pool DELETE Delete autoscale pool DELETE Delete autoscale pool and resources GET List history events GET List members

GET List All Autoscale Pools

/v2/droplets/autoscale
Authorizations: bearer_auth (1 scope)
Http: Bearer
Required scopes: droplet:read

OAuth Authentication

In order to interact with the DigitalOcean API, you or your application must authenticate.

The DigitalOcean API handles this through OAuth, an open standard for authorization. OAuth allows you to delegate access to your account. Scopes can be used to grant full access, read-only access, or access to a specific set of endpoints.

You can generate an OAuth token by visiting the Apps & API section of the DigitalOcean control panel for your account.

An OAuth token functions as a complete authentication request. In effect, it acts as a substitute for a username and password pair.

Because of this, it is absolutely essential that you keep your OAuth tokens secure. In fact, upon generation, the web interface will only display each token a single time in order to prevent the token from being compromised.

DigitalOcean access tokens begin with an identifiable prefix in order to distinguish them from other similar tokens.

  • dop_v1_ for personal access tokens generated in the control panel
  • doo_v1_ for tokens generated by applications using the OAuth flow
  • dor_v1_ for OAuth refresh tokens

Scopes

Scopes act like permissions assigned to an API token. These permissions determine what actions the token can perform. You can create API tokens that grant read-only access, full access, or limited access to specific endpoints by using custom scopes.

Generally, scopes are designed to match HTTP verbs and common CRUD operations (Create, Read, Update, Delete).

HTTP Verb CRUD Operation Scope
GET Read <resource>:read
POST Create <resource>:create
PUT/PATCH Update <resource>:update
DELETE Delete <resource>:delete

For example, creating a new Droplet by making a POST request to the /v2/droplets endpoint requires the droplet:create scope while listing Droplets by making a GET request to the /v2/droplets endpoint requires the droplet:read scope.

Each endpoint below specifies which scope is required to access it when using custom scopes.

How to Authenticate with OAuth

In order to make an authenticated request, include a bearer-type Authorization header containing your OAuth token. All requests must be made over HTTPS.

Authenticate with a Bearer Authorization Header

curl -X $HTTP_METHOD -H "Authorization: Bearer $DIGITALOCEAN_TOKEN" "https://api.digitalocean.com/v2/$OBJECT"

To list all autoscale pools in your team, send a GET request to /v2/droplets/autoscale. The response body will be a JSON object with a key of autoscale_pools containing an array of autoscale pool objects. These each contain the standard autoscale pool attributes.

Query Parameters

per_page integer 1 – 200 optional
Example: 2

Number of items returned per page

Default: 20
page integer >= 1 optional
Example: 1

Which 'page' of paginated results to return.

Default: 1
name string optional
Example: my-autoscale-pool

The name of the autoscale pool

Request: /v2/droplets/autoscale
curl -X GET \
  -H "Content-Type: application/json" \
  -H "Authorization: Bearer $DIGITALOCEAN_TOKEN" \
  "https://api.digitalocean.com/v2/droplets/autoscale?page=1&per_page=1"

Responses

200

A JSON object with a key of autoscale_pools.
Response Headers
ratelimit-limit integer

The default limit on number of requests that can be made per hour and per minute. Current rate limits are 5000 requests per hour and 250 requests per minute.

ratelimit-remaining integer

The number of requests in your hourly quota that remain before you hit your request limit. See https://docs.digitalocean.com/reference/api/reference/#rate-limit for information about how requests expire.

ratelimit-reset integer

The time when the oldest request will expire. The value is given in Unix epoch time. See https://docs.digitalocean.com/reference/api/reference/#rate-limit for information about how requests expire.

Response Schema: application/json
autoscale_pools array of object optional
Show child properties
active_resources_count integer required
Example: 1

The number of active Droplets in the autoscale pool.

config object required

The scaling configuration for an autoscale pool, which is how the pool scales up and down (either by resource utilization or static configuration).

One of:
Autoscale Pool Static Config
target_number_instances integer required
Example: 3

Fixed number of instances in an autoscale pool.

Autoscale Pool Dynamic Config
cooldown_minutes integer optional
Example: 5

The number of minutes to wait between scaling events in an autoscale pool. Defaults to 10 minutes.

max_instances integer required
Example: 10

The maximum number of Droplets in an autoscale pool.

min_instances integer required
Example: 5

The minimum number of Droplets in an autoscale pool.

target_cpu_utilization number (float) optional
Example: 0.6

Target CPU utilization as a decimal.

target_memory_utilization number (float) optional
Example: 0.6

Target memory utilization as a decimal.

created_at string (date-time) required
Example: 2020-07-28T18:00:00Z

A time value given in ISO8601 combined date and time format that represents when the autoscale pool was created.

current_utilization object optional
Show child properties
cpu number (float) optional
Example: 0.0007338008770232183

The average CPU utilization of the autoscale pool.

memory number (float) optional
Example: 0.3588531587713522

The average memory utilization of the autoscale pool.

droplet_template object required
Show child properties
image string required
Example: ubuntu-20-04-x64

The Droplet image to be used for all Droplets in the autoscale pool. You may specify the slug or the image ID.

ipv6 boolean optional
Example: true

Assigns a unique IPv6 address to each of the Droplets in the autoscale pool.

name string optional
Example: my-droplet-name

The name(s) to be applied to all Droplets in the autoscale pool.

project_id string optional
Example: 746c6152-2fa2-11ed-92d3-27aaa54e4988

The project that the Droplets in the autoscale pool will belong to. Requires project:read scope.

region string (enum) required
Example: tor1

The datacenter in which all of the Droplets will be created.

size string required
Example: c-2

The Droplet size to be used for all Droplets in the autoscale pool.

ssh_keys array of string required
Example: ["88:66:90:d2:68:d5:b5:85:e3:26:26:11:31:57:e6:f8"]

The SSH keys to be installed on the Droplets in the autoscale pool. You can either specify the key ID or the fingerprint. Requires ssh_key:read scope.

tags array of string optional
Example: ["my-tag"]

The tags to apply to each of the Droplets in the autoscale pool. Requires tag:read scope.

user_data string optional

A string containing user data that cloud-init consumes to configure a Droplet on first boot. User data is often a cloud-config file or Bash script. It must be plain text and may not exceed 64 KiB in size.

vpc_uuid string optional
Example: 760e09ef-dc84-11e8-981e-3cfdfeaae000

The VPC where the Droplets in the autoscale pool will be created. The VPC must be in the region where you want to create the Droplets. Requires vpc:read scope.

with_droplet_agent boolean optional
Example: true

Installs the Droplet agent. This must be set to true to monitor Droplets for resource utilization scaling.

id string required
Example: 0d3db13e-a604-4944-9827-7ec2642d32ac

A unique identifier for each autoscale pool instance. This is automatically generated upon autoscale pool creation.

name string required
Example: my-autoscale-pool

The human-readable name set for the autoscale pool.

status string, one of: active, deleting, error required
Example: active

The current status of the autoscale pool.

updated_at string (date-time) required
Example: 2020-07-28T18:00:00Z

A time value given in ISO8601 combined date and time format that represents when the autoscale pool was last updated.

links object optional
Show child properties
pages anyOf optional
One of:
Forward Links
last string optional
Example: https://api.digitalocean.com/v2/images?page=2

URI of the last page of the results.

next string optional
Example: https://api.digitalocean.com/v2/images?page=2

URI of the next page of the results.

Backward Links
first string optional
Example: https://api.digitalocean.com/v2/images?page=1

URI of the first page of the results.

prev string optional
Example: https://api.digitalocean.com/v2/images?page=1

URI of the previous page of the results.

meta object required
401

Authentication failed due to invalid credentials.
Response Headers
ratelimit-limit integer

The default limit on number of requests that can be made per hour and per minute. Current rate limits are 5000 requests per hour and 250 requests per minute.

ratelimit-remaining integer

The number of requests in your hourly quota that remain before you hit your request limit. See https://docs.digitalocean.com/reference/api/reference/#rate-limit for information about how requests expire.

ratelimit-reset integer

The time when the oldest request will expire. The value is given in Unix epoch time. See https://docs.digitalocean.com/reference/api/reference/#rate-limit for information about how requests expire.

Response Schema: application/json
id string required
Example: not_found

A short identifier corresponding to the HTTP status code returned. For example, the ID for a response returning a 404 status code would be "not_found."

message string required
Example: The resource you were accessing could not be found.

A message providing additional information about the error, including details to help resolve it when possible.

request_id string optional
Example: 4d9d8375-3c56-4925-a3e7-eb137fed17e9

Optionally, some endpoints may include a request ID that should be provided when reporting bugs or opening support tickets to help identify the issue.

429

The API rate limit has been exceeded.
Response Headers
ratelimit-limit integer

The default limit on number of requests that can be made per hour and per minute. Current rate limits are 5000 requests per hour and 250 requests per minute.

ratelimit-remaining integer

The number of requests in your hourly quota that remain before you hit your request limit. See https://docs.digitalocean.com/reference/api/reference/#rate-limit for information about how requests expire.

ratelimit-reset integer

The time when the oldest request will expire. The value is given in Unix epoch time. See https://docs.digitalocean.com/reference/api/reference/#rate-limit for information about how requests expire.

Response Schema: application/json
id string required
Example: not_found

A short identifier corresponding to the HTTP status code returned. For example, the ID for a response returning a 404 status code would be "not_found."

message string required
Example: The resource you were accessing could not be found.

A message providing additional information about the error, including details to help resolve it when possible.

request_id string optional
Example: 4d9d8375-3c56-4925-a3e7-eb137fed17e9

Optionally, some endpoints may include a request ID that should be provided when reporting bugs or opening support tickets to help identify the issue.

500

There was a server error.
Response Headers
ratelimit-limit integer

The default limit on number of requests that can be made per hour and per minute. Current rate limits are 5000 requests per hour and 250 requests per minute.

ratelimit-remaining integer

The number of requests in your hourly quota that remain before you hit your request limit. See https://docs.digitalocean.com/reference/api/reference/#rate-limit for information about how requests expire.

ratelimit-reset integer

The time when the oldest request will expire. The value is given in Unix epoch time. See https://docs.digitalocean.com/reference/api/reference/#rate-limit for information about how requests expire.

Response Schema: application/json
id string required
Example: not_found

A short identifier corresponding to the HTTP status code returned. For example, the ID for a response returning a 404 status code would be "not_found."

message string required
Example: The resource you were accessing could not be found.

A message providing additional information about the error, including details to help resolve it when possible.

request_id string optional
Example: 4d9d8375-3c56-4925-a3e7-eb137fed17e9

Optionally, some endpoints may include a request ID that should be provided when reporting bugs or opening support tickets to help identify the issue.

default

There was an unexpected error.
Response Headers
ratelimit-limit integer

The default limit on number of requests that can be made per hour and per minute. Current rate limits are 5000 requests per hour and 250 requests per minute.

ratelimit-remaining integer

The number of requests in your hourly quota that remain before you hit your request limit. See https://docs.digitalocean.com/reference/api/reference/#rate-limit for information about how requests expire.

ratelimit-reset integer

The time when the oldest request will expire. The value is given in Unix epoch time. See https://docs.digitalocean.com/reference/api/reference/#rate-limit for information about how requests expire.

Response Schema: application/json
id string required
Example: not_found

A short identifier corresponding to the HTTP status code returned. For example, the ID for a response returning a 404 status code would be "not_found."

message string required
Example: The resource you were accessing could not be found.

A message providing additional information about the error, including details to help resolve it when possible.

request_id string optional
Example: 4d9d8375-3c56-4925-a3e7-eb137fed17e9

Optionally, some endpoints may include a request ID that should be provided when reporting bugs or opening support tickets to help identify the issue.

Response
{
  "autoscale_pools": [
    {
      "active_resources_count": 1,
      "config": {
        "cooldown_minutes": 10,
        "max_instances": 5,
        "min_instances": 1,
        "target_cpu_utilization": 0.5
      },
      "created_at": "2020-11-19T20:27:18Z",
      "current_utilization": {
        "cpu": 0.0007338008770232183,
        "memory": 0.3588531587713522
      },
      "droplet_template": {
        "image": "ubuntu-20-04-x64",
        "ipv6": true,
        "name": "droplet-name",
        "project_id": "746c6152-2fa2-11ed-92d3-27aaa54e4988",
        "region": "tor1",
        "size": "c-2",
        "ssh_keys": [
          "3b:16:e4:bf:8b:00:8b:b8:59:8c:a9:d3:f0:19:fa:45"
        ],
        "tags": [
          "my-tag"
        ],
        "user_data": "#cloud-config\nruncmd:\n  - touch /test.txt\n",
        "vpc_uuid": "760e09ef-dc84-11e8-981e-3cfdfeaae000",
        "with_droplet_agent": true
      },
      "id": "0d3db13e-a604-4944-9827-7ec2642d32ac",
      "name": "test-autoscaler-group-01",
      "status": "active",
      "updated_at": "2020-12-01T00:42:16Z"
    }
  ],
  "links": {
    "pages": null
  },
  "meta": {
    "total": 1
  }
}
{
  "id": "unauthorized",
  "message": "Unable to authenticate you."
}
{
  "id": "too_many_requests",
  "message": "API rate limit exceeded."
}
{
  "id": "server_error",
  "message": "Unexpected server-side error"
}
{
  "id": "example_error",
  "message": "some error message"
}

POST Create a New Autoscale Pool

/v2/droplets/autoscale
Authorizations: bearer_auth (1 scope)
Http: Bearer
Required scopes: droplet:create

OAuth Authentication

In order to interact with the DigitalOcean API, you or your application must authenticate.

The DigitalOcean API handles this through OAuth, an open standard for authorization. OAuth allows you to delegate access to your account. Scopes can be used to grant full access, read-only access, or access to a specific set of endpoints.

You can generate an OAuth token by visiting the Apps & API section of the DigitalOcean control panel for your account.

An OAuth token functions as a complete authentication request. In effect, it acts as a substitute for a username and password pair.

Because of this, it is absolutely essential that you keep your OAuth tokens secure. In fact, upon generation, the web interface will only display each token a single time in order to prevent the token from being compromised.

DigitalOcean access tokens begin with an identifiable prefix in order to distinguish them from other similar tokens.

  • dop_v1_ for personal access tokens generated in the control panel
  • doo_v1_ for tokens generated by applications using the OAuth flow
  • dor_v1_ for OAuth refresh tokens

Scopes

Scopes act like permissions assigned to an API token. These permissions determine what actions the token can perform. You can create API tokens that grant read-only access, full access, or limited access to specific endpoints by using custom scopes.

Generally, scopes are designed to match HTTP verbs and common CRUD operations (Create, Read, Update, Delete).

HTTP Verb CRUD Operation Scope
GET Read <resource>:read
POST Create <resource>:create
PUT/PATCH Update <resource>:update
DELETE Delete <resource>:delete

For example, creating a new Droplet by making a POST request to the /v2/droplets endpoint requires the droplet:create scope while listing Droplets by making a GET request to the /v2/droplets endpoint requires the droplet:read scope.

Each endpoint below specifies which scope is required to access it when using custom scopes.

How to Authenticate with OAuth

In order to make an authenticated request, include a bearer-type Authorization header containing your OAuth token. All requests must be made over HTTPS.

Authenticate with a Bearer Authorization Header

curl -X $HTTP_METHOD -H "Authorization: Bearer $DIGITALOCEAN_TOKEN" "https://api.digitalocean.com/v2/$OBJECT"

To create a new autoscale pool, send a POST request to /v2/droplets/autoscale setting the required attributes.

The response body will contain a JSON object with a key called autoscale_pool containing the standard attributes for the new autoscale pool.

Request Body: application/json

config object required

The scaling configuration for an autoscale pool, which is how the pool scales up and down (either by resource utilization or static configuration).

One of:
Autoscale Pool Static Config
target_number_instances integer required
Example: 3

Fixed number of instances in an autoscale pool.

Autoscale Pool Dynamic Config
cooldown_minutes integer optional
Example: 5

The number of minutes to wait between scaling events in an autoscale pool. Defaults to 10 minutes.

max_instances integer required
Example: 10

The maximum number of Droplets in an autoscale pool.

min_instances integer required
Example: 5

The minimum number of Droplets in an autoscale pool.

target_cpu_utilization number (float) optional
Example: 0.6

Target CPU utilization as a decimal.

target_memory_utilization number (float) optional
Example: 0.6

Target memory utilization as a decimal.

droplet_template object required
Show child properties
image string required
Example: ubuntu-20-04-x64

The Droplet image to be used for all Droplets in the autoscale pool. You may specify the slug or the image ID.

ipv6 boolean optional
Example: true

Assigns a unique IPv6 address to each of the Droplets in the autoscale pool.

name string optional
Example: my-droplet-name

The name(s) to be applied to all Droplets in the autoscale pool.

project_id string optional
Example: 746c6152-2fa2-11ed-92d3-27aaa54e4988

The project that the Droplets in the autoscale pool will belong to. Requires project:read scope.

region string (enum) required
Example: tor1

The datacenter in which all of the Droplets will be created.

size string required
Example: c-2

The Droplet size to be used for all Droplets in the autoscale pool.

ssh_keys array of string required
Example: ["88:66:90:d2:68:d5:b5:85:e3:26:26:11:31:57:e6:f8"]

The SSH keys to be installed on the Droplets in the autoscale pool. You can either specify the key ID or the fingerprint. Requires ssh_key:read scope.

tags array of string optional
Example: ["my-tag"]

The tags to apply to each of the Droplets in the autoscale pool. Requires tag:read scope.

user_data string optional

A string containing user data that cloud-init consumes to configure a Droplet on first boot. User data is often a cloud-config file or Bash script. It must be plain text and may not exceed 64 KiB in size.

vpc_uuid string optional
Example: 760e09ef-dc84-11e8-981e-3cfdfeaae000

The VPC where the Droplets in the autoscale pool will be created. The VPC must be in the region where you want to create the Droplets. Requires vpc:read scope.

with_droplet_agent boolean optional
Example: true

Installs the Droplet agent. This must be set to true to monitor Droplets for resource utilization scaling.

name string required
Example: my-autoscale-pool

The human-readable name of the autoscale pool. This field cannot be updated

Request: /v2/droplets/autoscale
Content type application/json
Example 
{
  "config": {
    "cooldown_minutes": 10,
    "max_instances": 5,
    "min_instances": 1,
    "target_cpu_utilization": 0.5
  },
  "droplet_template": {
    "backups": true,
    "image": "ubuntu-20-04-x64",
    "ipv6": true,
    "monitoring": true,
    "name": "example.com",
    "region": "nyc3",
    "size": "c-2",
    "ssh_keys": [
      "3b:16:e4:bf:8b:00:8b:b8:59:8c:a9:d3:f0:19:fa:45"
    ],
    "tags": [
      "env:prod",
      "web"
    ],
    "user_data": "#cloud-config\nruncmd:\n  - touch /test.txt\n",
    "vpc_uuid": "760e09ef-dc84-11e8-981e-3cfdfeaae000"
  },
  "name": "my-autoscale-pool"
}
curl -X POST \
  -H "Content-Type: application/json" \
  -H "Authorization: Bearer $DIGITALOCEAN_TOKEN" \
  -d '{
    "name": "test-autoscalergroup",
    "config": {
      "min_instances": 1,
      "max_instances": 5,
      "target_cpu_utilization": 0.5,
      "cooldown_minutes": 5
    },
    "droplet_template": {
      "size": "c-2",
      "region": "tor1",
      "image": "ubuntu-20-04-x64",
      "tags": [
        "test-ag-01"
      ],
      "ssh_keys": [
        "392594",
        "385255"
      ],
      "vpc_uuid": "c472520a-831e-4770-8135-542c57a69daa",
      "ipv6": true,
      "user_data": "\n#cloud-config\nruncmd:\n- apt-get update\n"
    }
  }' \
  "https://api.digitalocean.com/v2/droplets/autoscale"

Responses

202

Accepted
Response Headers
ratelimit-limit integer

The default limit on number of requests that can be made per hour and per minute. Current rate limits are 5000 requests per hour and 250 requests per minute.

ratelimit-remaining integer

The number of requests in your hourly quota that remain before you hit your request limit. See https://docs.digitalocean.com/reference/api/reference/#rate-limit for information about how requests expire.

ratelimit-reset integer

The time when the oldest request will expire. The value is given in Unix epoch time. See https://docs.digitalocean.com/reference/api/reference/#rate-limit for information about how requests expire.

Response Schema: application/json
autoscale_pool object optional
Show child properties
active_resources_count integer required
Example: 1

The number of active Droplets in the autoscale pool.

config object required

The scaling configuration for an autoscale pool, which is how the pool scales up and down (either by resource utilization or static configuration).

One of:
Autoscale Pool Static Config
target_number_instances integer required
Example: 3

Fixed number of instances in an autoscale pool.

Autoscale Pool Dynamic Config
cooldown_minutes integer optional
Example: 5

The number of minutes to wait between scaling events in an autoscale pool. Defaults to 10 minutes.

max_instances integer required
Example: 10

The maximum number of Droplets in an autoscale pool.

min_instances integer required
Example: 5

The minimum number of Droplets in an autoscale pool.

target_cpu_utilization number (float) optional
Example: 0.6

Target CPU utilization as a decimal.

target_memory_utilization number (float) optional
Example: 0.6

Target memory utilization as a decimal.

created_at string (date-time) required
Example: 2020-07-28T18:00:00Z

A time value given in ISO8601 combined date and time format that represents when the autoscale pool was created.

current_utilization object optional
Show child properties
cpu number (float) optional
Example: 0.0007338008770232183

The average CPU utilization of the autoscale pool.

memory number (float) optional
Example: 0.3588531587713522

The average memory utilization of the autoscale pool.

droplet_template object required
Show child properties
image string required
Example: ubuntu-20-04-x64

The Droplet image to be used for all Droplets in the autoscale pool. You may specify the slug or the image ID.

ipv6 boolean optional
Example: true

Assigns a unique IPv6 address to each of the Droplets in the autoscale pool.

name string optional
Example: my-droplet-name

The name(s) to be applied to all Droplets in the autoscale pool.

project_id string optional
Example: 746c6152-2fa2-11ed-92d3-27aaa54e4988

The project that the Droplets in the autoscale pool will belong to. Requires project:read scope.

region string (enum) required
Example: tor1

The datacenter in which all of the Droplets will be created.

size string required
Example: c-2

The Droplet size to be used for all Droplets in the autoscale pool.

ssh_keys array of string required
Example: ["88:66:90:d2:68:d5:b5:85:e3:26:26:11:31:57:e6:f8"]

The SSH keys to be installed on the Droplets in the autoscale pool. You can either specify the key ID or the fingerprint. Requires ssh_key:read scope.

tags array of string optional
Example: ["my-tag"]

The tags to apply to each of the Droplets in the autoscale pool. Requires tag:read scope.

user_data string optional

A string containing user data that cloud-init consumes to configure a Droplet on first boot. User data is often a cloud-config file or Bash script. It must be plain text and may not exceed 64 KiB in size.

vpc_uuid string optional
Example: 760e09ef-dc84-11e8-981e-3cfdfeaae000

The VPC where the Droplets in the autoscale pool will be created. The VPC must be in the region where you want to create the Droplets. Requires vpc:read scope.

with_droplet_agent boolean optional
Example: true

Installs the Droplet agent. This must be set to true to monitor Droplets for resource utilization scaling.

id string required
Example: 0d3db13e-a604-4944-9827-7ec2642d32ac

A unique identifier for each autoscale pool instance. This is automatically generated upon autoscale pool creation.

name string required
Example: my-autoscale-pool

The human-readable name set for the autoscale pool.

status string, one of: active, deleting, error required
Example: active

The current status of the autoscale pool.

updated_at string (date-time) required
Example: 2020-07-28T18:00:00Z

A time value given in ISO8601 combined date and time format that represents when the autoscale pool was last updated.

401

Authentication failed due to invalid credentials.
Response Headers
ratelimit-limit integer

The default limit on number of requests that can be made per hour and per minute. Current rate limits are 5000 requests per hour and 250 requests per minute.

ratelimit-remaining integer

The number of requests in your hourly quota that remain before you hit your request limit. See https://docs.digitalocean.com/reference/api/reference/#rate-limit for information about how requests expire.

ratelimit-reset integer

The time when the oldest request will expire. The value is given in Unix epoch time. See https://docs.digitalocean.com/reference/api/reference/#rate-limit for information about how requests expire.

Response Schema: application/json
id string required
Example: not_found

A short identifier corresponding to the HTTP status code returned. For example, the ID for a response returning a 404 status code would be "not_found."

message string required
Example: The resource you were accessing could not be found.

A message providing additional information about the error, including details to help resolve it when possible.

request_id string optional
Example: 4d9d8375-3c56-4925-a3e7-eb137fed17e9

Optionally, some endpoints may include a request ID that should be provided when reporting bugs or opening support tickets to help identify the issue.

429

The API rate limit has been exceeded.
Response Headers
ratelimit-limit integer

The default limit on number of requests that can be made per hour and per minute. Current rate limits are 5000 requests per hour and 250 requests per minute.

ratelimit-remaining integer

The number of requests in your hourly quota that remain before you hit your request limit. See https://docs.digitalocean.com/reference/api/reference/#rate-limit for information about how requests expire.

ratelimit-reset integer

The time when the oldest request will expire. The value is given in Unix epoch time. See https://docs.digitalocean.com/reference/api/reference/#rate-limit for information about how requests expire.

Response Schema: application/json
id string required
Example: not_found

A short identifier corresponding to the HTTP status code returned. For example, the ID for a response returning a 404 status code would be "not_found."

message string required
Example: The resource you were accessing could not be found.

A message providing additional information about the error, including details to help resolve it when possible.

request_id string optional
Example: 4d9d8375-3c56-4925-a3e7-eb137fed17e9

Optionally, some endpoints may include a request ID that should be provided when reporting bugs or opening support tickets to help identify the issue.

500

There was a server error.
Response Headers
ratelimit-limit integer

The default limit on number of requests that can be made per hour and per minute. Current rate limits are 5000 requests per hour and 250 requests per minute.

ratelimit-remaining integer

The number of requests in your hourly quota that remain before you hit your request limit. See https://docs.digitalocean.com/reference/api/reference/#rate-limit for information about how requests expire.

ratelimit-reset integer

The time when the oldest request will expire. The value is given in Unix epoch time. See https://docs.digitalocean.com/reference/api/reference/#rate-limit for information about how requests expire.

Response Schema: application/json
id string required
Example: not_found

A short identifier corresponding to the HTTP status code returned. For example, the ID for a response returning a 404 status code would be "not_found."

message string required
Example: The resource you were accessing could not be found.

A message providing additional information about the error, including details to help resolve it when possible.

request_id string optional
Example: 4d9d8375-3c56-4925-a3e7-eb137fed17e9

Optionally, some endpoints may include a request ID that should be provided when reporting bugs or opening support tickets to help identify the issue.

default

There was an unexpected error.
Response Headers
ratelimit-limit integer

The default limit on number of requests that can be made per hour and per minute. Current rate limits are 5000 requests per hour and 250 requests per minute.

ratelimit-remaining integer

The number of requests in your hourly quota that remain before you hit your request limit. See https://docs.digitalocean.com/reference/api/reference/#rate-limit for information about how requests expire.

ratelimit-reset integer

The time when the oldest request will expire. The value is given in Unix epoch time. See https://docs.digitalocean.com/reference/api/reference/#rate-limit for information about how requests expire.

Response Schema: application/json
id string required
Example: not_found

A short identifier corresponding to the HTTP status code returned. For example, the ID for a response returning a 404 status code would be "not_found."

message string required
Example: The resource you were accessing could not be found.

A message providing additional information about the error, including details to help resolve it when possible.

request_id string optional
Example: 4d9d8375-3c56-4925-a3e7-eb137fed17e9

Optionally, some endpoints may include a request ID that should be provided when reporting bugs or opening support tickets to help identify the issue.

Response
Example 
{
  "autoscale_pool": {
    "active_resources_count": 1,
    "config": {
      "cooldown_minutes": 10,
      "max_instances": 5,
      "min_instances": 1,
      "target_cpu_utilization": 0.5
    },
    "created_at": "2020-11-19T20:27:18Z",
    "droplet_template": {
      "image": "ubuntu-20-04-x64",
      "ipv6": true,
      "name": "droplet-name",
      "project_id": "746c6152-2fa2-11ed-92d3-27aaa54e4988",
      "region": "tor1",
      "size": "c-2",
      "ssh_keys": [
        "3b:16:e4:bf:8b:00:8b:b8:59:8c:a9:d3:f0:19:fa:45"
      ],
      "tags": [
        "my-tag"
      ],
      "user_data": "#cloud-config\nruncmd:\n  - touch /test.txt\n",
      "vpc_uuid": "760e09ef-dc84-11e8-981e-3cfdfeaae000",
      "with_droplet_agent": true
    },
    "id": "0d3db13e-a604-4944-9827-7ec2642d32ac",
    "name": "test-autoscaler-group-01",
    "status": "active",
    "updated_at": "2020-12-01T00:42:16Z"
  }
}
{
  "id": "unauthorized",
  "message": "Unable to authenticate you."
}
{
  "id": "too_many_requests",
  "message": "API rate limit exceeded."
}
{
  "id": "server_error",
  "message": "Unexpected server-side error"
}
{
  "id": "example_error",
  "message": "some error message"
}

GET Retrieve an Existing Autoscale Pool

/v2/droplets/autoscale/{autoscale_pool_id}
Authorizations: bearer_auth (1 scope)
Http: Bearer
Required scopes: droplet:read

OAuth Authentication

In order to interact with the DigitalOcean API, you or your application must authenticate.

The DigitalOcean API handles this through OAuth, an open standard for authorization. OAuth allows you to delegate access to your account. Scopes can be used to grant full access, read-only access, or access to a specific set of endpoints.

You can generate an OAuth token by visiting the Apps & API section of the DigitalOcean control panel for your account.

An OAuth token functions as a complete authentication request. In effect, it acts as a substitute for a username and password pair.

Because of this, it is absolutely essential that you keep your OAuth tokens secure. In fact, upon generation, the web interface will only display each token a single time in order to prevent the token from being compromised.

DigitalOcean access tokens begin with an identifiable prefix in order to distinguish them from other similar tokens.

  • dop_v1_ for personal access tokens generated in the control panel
  • doo_v1_ for tokens generated by applications using the OAuth flow
  • dor_v1_ for OAuth refresh tokens

Scopes

Scopes act like permissions assigned to an API token. These permissions determine what actions the token can perform. You can create API tokens that grant read-only access, full access, or limited access to specific endpoints by using custom scopes.

Generally, scopes are designed to match HTTP verbs and common CRUD operations (Create, Read, Update, Delete).

HTTP Verb CRUD Operation Scope
GET Read <resource>:read
POST Create <resource>:create
PUT/PATCH Update <resource>:update
DELETE Delete <resource>:delete

For example, creating a new Droplet by making a POST request to the /v2/droplets endpoint requires the droplet:create scope while listing Droplets by making a GET request to the /v2/droplets endpoint requires the droplet:read scope.

Each endpoint below specifies which scope is required to access it when using custom scopes.

How to Authenticate with OAuth

In order to make an authenticated request, include a bearer-type Authorization header containing your OAuth token. All requests must be made over HTTPS.

Authenticate with a Bearer Authorization Header

curl -X $HTTP_METHOD -H "Authorization: Bearer $DIGITALOCEAN_TOKEN" "https://api.digitalocean.com/v2/$OBJECT"

To show information about an individual autoscale pool, send a GET request to /v2/droplets/autoscale/$AUTOSCALE_POOL_ID.

Path Parameters

autoscale_pool_id string required
Example: 0d3db13e-a604-4944-9827-7ec2642d32ac

A unique identifier for an autoscale pool.

Request: /v2/droplets/autoscale/{autoscale_pool_id}
curl -X GET \
  -H "Content-Type: application/json" \
  -H "Authorization: Bearer $DIGITALOCEAN_TOKEN" \
  "https://api.digitalocean.com/v2/droplets/autoscale/880fee37-d07a-4f94-94a0-f07d9fc7bbb4"

Responses

200

The response will be a JSON object with a key called autoscale_pool. This will be set to a JSON object that contains the standard autoscale pool attributes.
Response Headers
ratelimit-limit integer

The default limit on number of requests that can be made per hour and per minute. Current rate limits are 5000 requests per hour and 250 requests per minute.

ratelimit-remaining integer

The number of requests in your hourly quota that remain before you hit your request limit. See https://docs.digitalocean.com/reference/api/reference/#rate-limit for information about how requests expire.

ratelimit-reset integer

The time when the oldest request will expire. The value is given in Unix epoch time. See https://docs.digitalocean.com/reference/api/reference/#rate-limit for information about how requests expire.

Response Schema: application/json
autoscale_pool object optional
Show child properties
active_resources_count integer required
Example: 1

The number of active Droplets in the autoscale pool.

config object required

The scaling configuration for an autoscale pool, which is how the pool scales up and down (either by resource utilization or static configuration).

One of:
Autoscale Pool Static Config
target_number_instances integer required
Example: 3

Fixed number of instances in an autoscale pool.

Autoscale Pool Dynamic Config
cooldown_minutes integer optional
Example: 5

The number of minutes to wait between scaling events in an autoscale pool. Defaults to 10 minutes.

max_instances integer required
Example: 10

The maximum number of Droplets in an autoscale pool.

min_instances integer required
Example: 5

The minimum number of Droplets in an autoscale pool.

target_cpu_utilization number (float) optional
Example: 0.6

Target CPU utilization as a decimal.

target_memory_utilization number (float) optional
Example: 0.6

Target memory utilization as a decimal.

created_at string (date-time) required
Example: 2020-07-28T18:00:00Z

A time value given in ISO8601 combined date and time format that represents when the autoscale pool was created.

current_utilization object optional
Show child properties
cpu number (float) optional
Example: 0.0007338008770232183

The average CPU utilization of the autoscale pool.

memory number (float) optional
Example: 0.3588531587713522

The average memory utilization of the autoscale pool.

droplet_template object required
Show child properties
image string required
Example: ubuntu-20-04-x64

The Droplet image to be used for all Droplets in the autoscale pool. You may specify the slug or the image ID.

ipv6 boolean optional
Example: true

Assigns a unique IPv6 address to each of the Droplets in the autoscale pool.

name string optional
Example: my-droplet-name

The name(s) to be applied to all Droplets in the autoscale pool.

project_id string optional
Example: 746c6152-2fa2-11ed-92d3-27aaa54e4988

The project that the Droplets in the autoscale pool will belong to. Requires project:read scope.

region string (enum) required
Example: tor1

The datacenter in which all of the Droplets will be created.

size string required
Example: c-2

The Droplet size to be used for all Droplets in the autoscale pool.

ssh_keys array of string required
Example: ["88:66:90:d2:68:d5:b5:85:e3:26:26:11:31:57:e6:f8"]

The SSH keys to be installed on the Droplets in the autoscale pool. You can either specify the key ID or the fingerprint. Requires ssh_key:read scope.

tags array of string optional
Example: ["my-tag"]

The tags to apply to each of the Droplets in the autoscale pool. Requires tag:read scope.

user_data string optional

A string containing user data that cloud-init consumes to configure a Droplet on first boot. User data is often a cloud-config file or Bash script. It must be plain text and may not exceed 64 KiB in size.

vpc_uuid string optional
Example: 760e09ef-dc84-11e8-981e-3cfdfeaae000

The VPC where the Droplets in the autoscale pool will be created. The VPC must be in the region where you want to create the Droplets. Requires vpc:read scope.

with_droplet_agent boolean optional
Example: true

Installs the Droplet agent. This must be set to true to monitor Droplets for resource utilization scaling.

id string required
Example: 0d3db13e-a604-4944-9827-7ec2642d32ac

A unique identifier for each autoscale pool instance. This is automatically generated upon autoscale pool creation.

name string required
Example: my-autoscale-pool

The human-readable name set for the autoscale pool.

status string, one of: active, deleting, error required
Example: active

The current status of the autoscale pool.

updated_at string (date-time) required
Example: 2020-07-28T18:00:00Z

A time value given in ISO8601 combined date and time format that represents when the autoscale pool was last updated.

401

Authentication failed due to invalid credentials.
Response Headers
ratelimit-limit integer

The default limit on number of requests that can be made per hour and per minute. Current rate limits are 5000 requests per hour and 250 requests per minute.

ratelimit-remaining integer

The number of requests in your hourly quota that remain before you hit your request limit. See https://docs.digitalocean.com/reference/api/reference/#rate-limit for information about how requests expire.

ratelimit-reset integer

The time when the oldest request will expire. The value is given in Unix epoch time. See https://docs.digitalocean.com/reference/api/reference/#rate-limit for information about how requests expire.

Response Schema: application/json
id string required
Example: not_found

A short identifier corresponding to the HTTP status code returned. For example, the ID for a response returning a 404 status code would be "not_found."

message string required
Example: The resource you were accessing could not be found.

A message providing additional information about the error, including details to help resolve it when possible.

request_id string optional
Example: 4d9d8375-3c56-4925-a3e7-eb137fed17e9

Optionally, some endpoints may include a request ID that should be provided when reporting bugs or opening support tickets to help identify the issue.

404

The resource was not found.
Response Headers
ratelimit-limit integer

The default limit on number of requests that can be made per hour and per minute. Current rate limits are 5000 requests per hour and 250 requests per minute.

ratelimit-remaining integer

The number of requests in your hourly quota that remain before you hit your request limit. See https://docs.digitalocean.com/reference/api/reference/#rate-limit for information about how requests expire.

ratelimit-reset integer

The time when the oldest request will expire. The value is given in Unix epoch time. See https://docs.digitalocean.com/reference/api/reference/#rate-limit for information about how requests expire.

Response Schema: application/json
id string required
Example: not_found

A short identifier corresponding to the HTTP status code returned. For example, the ID for a response returning a 404 status code would be "not_found."

message string required
Example: The resource you were accessing could not be found.

A message providing additional information about the error, including details to help resolve it when possible.

request_id string optional
Example: 4d9d8375-3c56-4925-a3e7-eb137fed17e9

Optionally, some endpoints may include a request ID that should be provided when reporting bugs or opening support tickets to help identify the issue.

429

The API rate limit has been exceeded.
Response Headers
ratelimit-limit integer

The default limit on number of requests that can be made per hour and per minute. Current rate limits are 5000 requests per hour and 250 requests per minute.

ratelimit-remaining integer

The number of requests in your hourly quota that remain before you hit your request limit. See https://docs.digitalocean.com/reference/api/reference/#rate-limit for information about how requests expire.

ratelimit-reset integer

The time when the oldest request will expire. The value is given in Unix epoch time. See https://docs.digitalocean.com/reference/api/reference/#rate-limit for information about how requests expire.

Response Schema: application/json
id string required
Example: not_found

A short identifier corresponding to the HTTP status code returned. For example, the ID for a response returning a 404 status code would be "not_found."

message string required
Example: The resource you were accessing could not be found.

A message providing additional information about the error, including details to help resolve it when possible.

request_id string optional
Example: 4d9d8375-3c56-4925-a3e7-eb137fed17e9

Optionally, some endpoints may include a request ID that should be provided when reporting bugs or opening support tickets to help identify the issue.

500

There was a server error.
Response Headers
ratelimit-limit integer

The default limit on number of requests that can be made per hour and per minute. Current rate limits are 5000 requests per hour and 250 requests per minute.

ratelimit-remaining integer

The number of requests in your hourly quota that remain before you hit your request limit. See https://docs.digitalocean.com/reference/api/reference/#rate-limit for information about how requests expire.

ratelimit-reset integer

The time when the oldest request will expire. The value is given in Unix epoch time. See https://docs.digitalocean.com/reference/api/reference/#rate-limit for information about how requests expire.

Response Schema: application/json
id string required
Example: not_found

A short identifier corresponding to the HTTP status code returned. For example, the ID for a response returning a 404 status code would be "not_found."

message string required
Example: The resource you were accessing could not be found.

A message providing additional information about the error, including details to help resolve it when possible.

request_id string optional
Example: 4d9d8375-3c56-4925-a3e7-eb137fed17e9

Optionally, some endpoints may include a request ID that should be provided when reporting bugs or opening support tickets to help identify the issue.

default

There was an unexpected error.
Response Headers
ratelimit-limit integer

The default limit on number of requests that can be made per hour and per minute. Current rate limits are 5000 requests per hour and 250 requests per minute.

ratelimit-remaining integer

The number of requests in your hourly quota that remain before you hit your request limit. See https://docs.digitalocean.com/reference/api/reference/#rate-limit for information about how requests expire.

ratelimit-reset integer

The time when the oldest request will expire. The value is given in Unix epoch time. See https://docs.digitalocean.com/reference/api/reference/#rate-limit for information about how requests expire.

Response Schema: application/json
id string required
Example: not_found

A short identifier corresponding to the HTTP status code returned. For example, the ID for a response returning a 404 status code would be "not_found."

message string required
Example: The resource you were accessing could not be found.

A message providing additional information about the error, including details to help resolve it when possible.

request_id string optional
Example: 4d9d8375-3c56-4925-a3e7-eb137fed17e9

Optionally, some endpoints may include a request ID that should be provided when reporting bugs or opening support tickets to help identify the issue.

Response
{
  "autoscale_pool": {
    "active_resources_count": 1,
    "config": {
      "cooldown_minutes": 10,
      "max_instances": 5,
      "min_instances": 1,
      "target_cpu_utilization": 0.5
    },
    "created_at": "2020-11-19T20:27:18Z",
    "current_utilization": {
      "cpu": 0.0007338008770232183,
      "memory": 0.3588531587713522
    },
    "droplet_template": {
      "image": "ubuntu-20-04-x64",
      "ipv6": true,
      "name": "droplet-name",
      "project_id": "746c6152-2fa2-11ed-92d3-27aaa54e4988",
      "region": "tor1",
      "size": "c-2",
      "ssh_keys": [
        "3b:16:e4:bf:8b:00:8b:b8:59:8c:a9:d3:f0:19:fa:45"
      ],
      "tags": [
        "my-tag"
      ],
      "user_data": "#cloud-config\nruncmd:\n  - touch /test.txt\n",
      "vpc_uuid": "760e09ef-dc84-11e8-981e-3cfdfeaae000",
      "with_droplet_agent": true
    },
    "id": "0d3db13e-a604-4944-9827-7ec2642d32ac",
    "name": "test-autoscaler-group-01",
    "status": "active",
    "updated_at": "2020-12-01T00:42:16Z"
  }
}
{
  "id": "unauthorized",
  "message": "Unable to authenticate you."
}
{
  "id": "not_found",
  "message": "The resource you requested could not be found."
}
{
  "id": "too_many_requests",
  "message": "API rate limit exceeded."
}
{
  "id": "server_error",
  "message": "Unexpected server-side error"
}
{
  "id": "example_error",
  "message": "some error message"
}

PUT Update Autoscale Pool

/v2/droplets/autoscale/{autoscale_pool_id}
Authorizations: bearer_auth (1 scope)
Http: Bearer
Required scopes: droplet:create

OAuth Authentication

In order to interact with the DigitalOcean API, you or your application must authenticate.

The DigitalOcean API handles this through OAuth, an open standard for authorization. OAuth allows you to delegate access to your account. Scopes can be used to grant full access, read-only access, or access to a specific set of endpoints.

You can generate an OAuth token by visiting the Apps & API section of the DigitalOcean control panel for your account.

An OAuth token functions as a complete authentication request. In effect, it acts as a substitute for a username and password pair.

Because of this, it is absolutely essential that you keep your OAuth tokens secure. In fact, upon generation, the web interface will only display each token a single time in order to prevent the token from being compromised.

DigitalOcean access tokens begin with an identifiable prefix in order to distinguish them from other similar tokens.

  • dop_v1_ for personal access tokens generated in the control panel
  • doo_v1_ for tokens generated by applications using the OAuth flow
  • dor_v1_ for OAuth refresh tokens

Scopes

Scopes act like permissions assigned to an API token. These permissions determine what actions the token can perform. You can create API tokens that grant read-only access, full access, or limited access to specific endpoints by using custom scopes.

Generally, scopes are designed to match HTTP verbs and common CRUD operations (Create, Read, Update, Delete).

HTTP Verb CRUD Operation Scope
GET Read <resource>:read
POST Create <resource>:create
PUT/PATCH Update <resource>:update
DELETE Delete <resource>:delete

For example, creating a new Droplet by making a POST request to the /v2/droplets endpoint requires the droplet:create scope while listing Droplets by making a GET request to the /v2/droplets endpoint requires the droplet:read scope.

Each endpoint below specifies which scope is required to access it when using custom scopes.

How to Authenticate with OAuth

In order to make an authenticated request, include a bearer-type Authorization header containing your OAuth token. All requests must be made over HTTPS.

Authenticate with a Bearer Authorization Header

curl -X $HTTP_METHOD -H "Authorization: Bearer $DIGITALOCEAN_TOKEN" "https://api.digitalocean.com/v2/$OBJECT"

To update the configuration of an existing autoscale pool, send a PUT request to /v2/droplets/autoscale/$AUTOSCALE_POOL_ID. The request must contain a full representation of the autoscale pool including existing attributes.

Path Parameters

autoscale_pool_id string required
Example: 0d3db13e-a604-4944-9827-7ec2642d32ac

A unique identifier for an autoscale pool.

Request Body: application/json

config object required

The scaling configuration for an autoscale pool, which is how the pool scales up and down (either by resource utilization or static configuration).

One of:
Autoscale Pool Static Config
target_number_instances integer required
Example: 3

Fixed number of instances in an autoscale pool.

Autoscale Pool Dynamic Config
cooldown_minutes integer optional
Example: 5

The number of minutes to wait between scaling events in an autoscale pool. Defaults to 10 minutes.

max_instances integer required
Example: 10

The maximum number of Droplets in an autoscale pool.

min_instances integer required
Example: 5

The minimum number of Droplets in an autoscale pool.

target_cpu_utilization number (float) optional
Example: 0.6

Target CPU utilization as a decimal.

target_memory_utilization number (float) optional
Example: 0.6

Target memory utilization as a decimal.

droplet_template object required
Show child properties
image string required
Example: ubuntu-20-04-x64

The Droplet image to be used for all Droplets in the autoscale pool. You may specify the slug or the image ID.

ipv6 boolean optional
Example: true

Assigns a unique IPv6 address to each of the Droplets in the autoscale pool.

name string optional
Example: my-droplet-name

The name(s) to be applied to all Droplets in the autoscale pool.

project_id string optional
Example: 746c6152-2fa2-11ed-92d3-27aaa54e4988

The project that the Droplets in the autoscale pool will belong to. Requires project:read scope.

region string (enum) required
Example: tor1

The datacenter in which all of the Droplets will be created.

size string required
Example: c-2

The Droplet size to be used for all Droplets in the autoscale pool.

ssh_keys array of string required
Example: ["88:66:90:d2:68:d5:b5:85:e3:26:26:11:31:57:e6:f8"]

The SSH keys to be installed on the Droplets in the autoscale pool. You can either specify the key ID or the fingerprint. Requires ssh_key:read scope.

tags array of string optional
Example: ["my-tag"]

The tags to apply to each of the Droplets in the autoscale pool. Requires tag:read scope.

user_data string optional

A string containing user data that cloud-init consumes to configure a Droplet on first boot. User data is often a cloud-config file or Bash script. It must be plain text and may not exceed 64 KiB in size.

vpc_uuid string optional
Example: 760e09ef-dc84-11e8-981e-3cfdfeaae000

The VPC where the Droplets in the autoscale pool will be created. The VPC must be in the region where you want to create the Droplets. Requires vpc:read scope.

with_droplet_agent boolean optional
Example: true

Installs the Droplet agent. This must be set to true to monitor Droplets for resource utilization scaling.

name string required
Example: my-autoscale-pool

The human-readable name of the autoscale pool. This field cannot be updated

Request: /v2/droplets/autoscale/{autoscale_pool_id}
Content type application/json 
{
  "config": {
    "target_number_instances": 2
  },
  "droplet_template": {
    "backups": true,
    "image": "ubuntu-20-04-x64",
    "ipv6": true,
    "monitoring": true,
    "name": "example.com",
    "region": "nyc3",
    "size": "c-2",
    "ssh_keys": [
      "3b:16:e4:bf:8b:00:8b:b8:59:8c:a9:d3:f0:19:fa:45"
    ],
    "tags": [
      "env:prod",
      "web"
    ],
    "user_data": "#cloud-config\nruncmd:\n  - touch /test.txt\n",
    "vpc_uuid": "760e09ef-dc84-11e8-981e-3cfdfeaae000"
  },
  "name": "my-autoscale-pool"
}
curl -X PUT \
  -H "Content-Type: application/json" \
  -H "Authorization: Bearer $DIGITALOCEAN_TOKEN" \
  -d '{
    "name": "test-autoscalergroup-01",
    "config": {
      "min_instances": 1,
      "max_instances": 5,
      "target_cpu_utilization": 0.5,
      "cooldown_minutes": 10
    },
    "droplet_template": {
      "size": "c-2",
      "region": "tor1",
      "image": "ubuntu-20-04-x64",
      "tags": [
        "test-ag-01"
      ],
      "ssh_keys": [
        "372862",
        "367582",
        "355790"
      ],
      "vpc_uuid": "4637280e-3842-4661-a628-a6f0392959d3",
      "with_droplet_agent": true,
      "ipv6": true,
      "user_data": "\n#cloud-config\nruncmd:\n- apt-get update\n"
    }
  }' \
  "https://api.digitalocean.com/v2/droplets/autoscale/d0067f19-c9bd-4d8c-b28b-e464fd1fb250"

Responses

200

Accepted
Response Headers
ratelimit-limit integer

The default limit on number of requests that can be made per hour and per minute. Current rate limits are 5000 requests per hour and 250 requests per minute.

ratelimit-remaining integer

The number of requests in your hourly quota that remain before you hit your request limit. See https://docs.digitalocean.com/reference/api/reference/#rate-limit for information about how requests expire.

ratelimit-reset integer

The time when the oldest request will expire. The value is given in Unix epoch time. See https://docs.digitalocean.com/reference/api/reference/#rate-limit for information about how requests expire.

Response Schema: application/json
autoscale_pool object optional
Show child properties
active_resources_count integer required
Example: 1

The number of active Droplets in the autoscale pool.

config object required

The scaling configuration for an autoscale pool, which is how the pool scales up and down (either by resource utilization or static configuration).

One of:
Autoscale Pool Static Config
target_number_instances integer required
Example: 3

Fixed number of instances in an autoscale pool.

Autoscale Pool Dynamic Config
cooldown_minutes integer optional
Example: 5

The number of minutes to wait between scaling events in an autoscale pool. Defaults to 10 minutes.

max_instances integer required
Example: 10

The maximum number of Droplets in an autoscale pool.

min_instances integer required
Example: 5

The minimum number of Droplets in an autoscale pool.

target_cpu_utilization number (float) optional
Example: 0.6

Target CPU utilization as a decimal.

target_memory_utilization number (float) optional
Example: 0.6

Target memory utilization as a decimal.

created_at string (date-time) required
Example: 2020-07-28T18:00:00Z

A time value given in ISO8601 combined date and time format that represents when the autoscale pool was created.

current_utilization object optional
Show child properties
cpu number (float) optional
Example: 0.0007338008770232183

The average CPU utilization of the autoscale pool.

memory number (float) optional
Example: 0.3588531587713522

The average memory utilization of the autoscale pool.

droplet_template object required
Show child properties
image string required
Example: ubuntu-20-04-x64

The Droplet image to be used for all Droplets in the autoscale pool. You may specify the slug or the image ID.

ipv6 boolean optional
Example: true

Assigns a unique IPv6 address to each of the Droplets in the autoscale pool.

name string optional
Example: my-droplet-name

The name(s) to be applied to all Droplets in the autoscale pool.

project_id string optional
Example: 746c6152-2fa2-11ed-92d3-27aaa54e4988

The project that the Droplets in the autoscale pool will belong to. Requires project:read scope.

region string (enum) required
Example: tor1

The datacenter in which all of the Droplets will be created.

size string required
Example: c-2

The Droplet size to be used for all Droplets in the autoscale pool.

ssh_keys array of string required
Example: ["88:66:90:d2:68:d5:b5:85:e3:26:26:11:31:57:e6:f8"]

The SSH keys to be installed on the Droplets in the autoscale pool. You can either specify the key ID or the fingerprint. Requires ssh_key:read scope.

tags array of string optional
Example: ["my-tag"]

The tags to apply to each of the Droplets in the autoscale pool. Requires tag:read scope.

user_data string optional

A string containing user data that cloud-init consumes to configure a Droplet on first boot. User data is often a cloud-config file or Bash script. It must be plain text and may not exceed 64 KiB in size.

vpc_uuid string optional
Example: 760e09ef-dc84-11e8-981e-3cfdfeaae000

The VPC where the Droplets in the autoscale pool will be created. The VPC must be in the region where you want to create the Droplets. Requires vpc:read scope.

with_droplet_agent boolean optional
Example: true

Installs the Droplet agent. This must be set to true to monitor Droplets for resource utilization scaling.

id string required
Example: 0d3db13e-a604-4944-9827-7ec2642d32ac

A unique identifier for each autoscale pool instance. This is automatically generated upon autoscale pool creation.

name string required
Example: my-autoscale-pool

The human-readable name set for the autoscale pool.

status string, one of: active, deleting, error required
Example: active

The current status of the autoscale pool.

updated_at string (date-time) required
Example: 2020-07-28T18:00:00Z

A time value given in ISO8601 combined date and time format that represents when the autoscale pool was last updated.

401

Authentication failed due to invalid credentials.
Response Headers
ratelimit-limit integer

The default limit on number of requests that can be made per hour and per minute. Current rate limits are 5000 requests per hour and 250 requests per minute.

ratelimit-remaining integer

The number of requests in your hourly quota that remain before you hit your request limit. See https://docs.digitalocean.com/reference/api/reference/#rate-limit for information about how requests expire.

ratelimit-reset integer

The time when the oldest request will expire. The value is given in Unix epoch time. See https://docs.digitalocean.com/reference/api/reference/#rate-limit for information about how requests expire.

Response Schema: application/json
id string required
Example: not_found

A short identifier corresponding to the HTTP status code returned. For example, the ID for a response returning a 404 status code would be "not_found."

message string required
Example: The resource you were accessing could not be found.

A message providing additional information about the error, including details to help resolve it when possible.

request_id string optional
Example: 4d9d8375-3c56-4925-a3e7-eb137fed17e9

Optionally, some endpoints may include a request ID that should be provided when reporting bugs or opening support tickets to help identify the issue.

404

The resource was not found.
Response Headers
ratelimit-limit integer

The default limit on number of requests that can be made per hour and per minute. Current rate limits are 5000 requests per hour and 250 requests per minute.

ratelimit-remaining integer

The number of requests in your hourly quota that remain before you hit your request limit. See https://docs.digitalocean.com/reference/api/reference/#rate-limit for information about how requests expire.

ratelimit-reset integer

The time when the oldest request will expire. The value is given in Unix epoch time. See https://docs.digitalocean.com/reference/api/reference/#rate-limit for information about how requests expire.

Response Schema: application/json
id string required
Example: not_found

A short identifier corresponding to the HTTP status code returned. For example, the ID for a response returning a 404 status code would be "not_found."

message string required
Example: The resource you were accessing could not be found.

A message providing additional information about the error, including details to help resolve it when possible.

request_id string optional
Example: 4d9d8375-3c56-4925-a3e7-eb137fed17e9

Optionally, some endpoints may include a request ID that should be provided when reporting bugs or opening support tickets to help identify the issue.

429

The API rate limit has been exceeded.
Response Headers
ratelimit-limit integer

The default limit on number of requests that can be made per hour and per minute. Current rate limits are 5000 requests per hour and 250 requests per minute.

ratelimit-remaining integer

The number of requests in your hourly quota that remain before you hit your request limit. See https://docs.digitalocean.com/reference/api/reference/#rate-limit for information about how requests expire.

ratelimit-reset integer

The time when the oldest request will expire. The value is given in Unix epoch time. See https://docs.digitalocean.com/reference/api/reference/#rate-limit for information about how requests expire.

Response Schema: application/json
id string required
Example: not_found

A short identifier corresponding to the HTTP status code returned. For example, the ID for a response returning a 404 status code would be "not_found."

message string required
Example: The resource you were accessing could not be found.

A message providing additional information about the error, including details to help resolve it when possible.

request_id string optional
Example: 4d9d8375-3c56-4925-a3e7-eb137fed17e9

Optionally, some endpoints may include a request ID that should be provided when reporting bugs or opening support tickets to help identify the issue.

500

There was a server error.
Response Headers
ratelimit-limit integer

The default limit on number of requests that can be made per hour and per minute. Current rate limits are 5000 requests per hour and 250 requests per minute.

ratelimit-remaining integer

The number of requests in your hourly quota that remain before you hit your request limit. See https://docs.digitalocean.com/reference/api/reference/#rate-limit for information about how requests expire.

ratelimit-reset integer

The time when the oldest request will expire. The value is given in Unix epoch time. See https://docs.digitalocean.com/reference/api/reference/#rate-limit for information about how requests expire.

Response Schema: application/json
id string required
Example: not_found

A short identifier corresponding to the HTTP status code returned. For example, the ID for a response returning a 404 status code would be "not_found."

message string required
Example: The resource you were accessing could not be found.

A message providing additional information about the error, including details to help resolve it when possible.

request_id string optional
Example: 4d9d8375-3c56-4925-a3e7-eb137fed17e9

Optionally, some endpoints may include a request ID that should be provided when reporting bugs or opening support tickets to help identify the issue.

default

There was an unexpected error.
Response Headers
ratelimit-limit integer

The default limit on number of requests that can be made per hour and per minute. Current rate limits are 5000 requests per hour and 250 requests per minute.

ratelimit-remaining integer

The number of requests in your hourly quota that remain before you hit your request limit. See https://docs.digitalocean.com/reference/api/reference/#rate-limit for information about how requests expire.

ratelimit-reset integer

The time when the oldest request will expire. The value is given in Unix epoch time. See https://docs.digitalocean.com/reference/api/reference/#rate-limit for information about how requests expire.

Response Schema: application/json
id string required
Example: not_found

A short identifier corresponding to the HTTP status code returned. For example, the ID for a response returning a 404 status code would be "not_found."

message string required
Example: The resource you were accessing could not be found.

A message providing additional information about the error, including details to help resolve it when possible.

request_id string optional
Example: 4d9d8375-3c56-4925-a3e7-eb137fed17e9

Optionally, some endpoints may include a request ID that should be provided when reporting bugs or opening support tickets to help identify the issue.

Response
Example 
{
  "autoscale_pool": {
    "active_resources_count": 1,
    "config": {
      "cooldown_minutes": 10,
      "max_instances": 5,
      "min_instances": 1,
      "target_cpu_utilization": 0.5
    },
    "created_at": "2020-11-19T20:27:18Z",
    "droplet_template": {
      "image": "ubuntu-20-04-x64",
      "ipv6": true,
      "name": "droplet-name",
      "project_id": "746c6152-2fa2-11ed-92d3-27aaa54e4988",
      "region": "tor1",
      "size": "c-2",
      "ssh_keys": [
        "3b:16:e4:bf:8b:00:8b:b8:59:8c:a9:d3:f0:19:fa:45"
      ],
      "tags": [
        "my-tag"
      ],
      "user_data": "#cloud-config\nruncmd:\n  - touch /test.txt\n",
      "vpc_uuid": "760e09ef-dc84-11e8-981e-3cfdfeaae000",
      "with_droplet_agent": true
    },
    "id": "0d3db13e-a604-4944-9827-7ec2642d32ac",
    "name": "test-autoscaler-group-01",
    "status": "active",
    "updated_at": "2020-12-01T00:42:16Z"
  }
}
{
  "id": "unauthorized",
  "message": "Unable to authenticate you."
}
{
  "id": "not_found",
  "message": "The resource you requested could not be found."
}
{
  "id": "too_many_requests",
  "message": "API rate limit exceeded."
}
{
  "id": "server_error",
  "message": "Unexpected server-side error"
}
{
  "id": "example_error",
  "message": "some error message"
}

DELETE Delete autoscale pool

/v2/droplets/autoscale/{autoscale_pool_id}
Authorizations: bearer_auth (1 scope)
Http: Bearer
Required scopes: droplet:delete

OAuth Authentication

In order to interact with the DigitalOcean API, you or your application must authenticate.

The DigitalOcean API handles this through OAuth, an open standard for authorization. OAuth allows you to delegate access to your account. Scopes can be used to grant full access, read-only access, or access to a specific set of endpoints.

You can generate an OAuth token by visiting the Apps & API section of the DigitalOcean control panel for your account.

An OAuth token functions as a complete authentication request. In effect, it acts as a substitute for a username and password pair.

Because of this, it is absolutely essential that you keep your OAuth tokens secure. In fact, upon generation, the web interface will only display each token a single time in order to prevent the token from being compromised.

DigitalOcean access tokens begin with an identifiable prefix in order to distinguish them from other similar tokens.

  • dop_v1_ for personal access tokens generated in the control panel
  • doo_v1_ for tokens generated by applications using the OAuth flow
  • dor_v1_ for OAuth refresh tokens

Scopes

Scopes act like permissions assigned to an API token. These permissions determine what actions the token can perform. You can create API tokens that grant read-only access, full access, or limited access to specific endpoints by using custom scopes.

Generally, scopes are designed to match HTTP verbs and common CRUD operations (Create, Read, Update, Delete).

HTTP Verb CRUD Operation Scope
GET Read <resource>:read
POST Create <resource>:create
PUT/PATCH Update <resource>:update
DELETE Delete <resource>:delete

For example, creating a new Droplet by making a POST request to the /v2/droplets endpoint requires the droplet:create scope while listing Droplets by making a GET request to the /v2/droplets endpoint requires the droplet:read scope.

Each endpoint below specifies which scope is required to access it when using custom scopes.

How to Authenticate with OAuth

In order to make an authenticated request, include a bearer-type Authorization header containing your OAuth token. All requests must be made over HTTPS.

Authenticate with a Bearer Authorization Header

curl -X $HTTP_METHOD -H "Authorization: Bearer $DIGITALOCEAN_TOKEN" "https://api.digitalocean.com/v2/$OBJECT"

To destroy an autoscale pool, send a DELETE request to the /v2/droplets/autoscale/$AUTOSCALE_POOL_ID endpoint.

A successful response will include a 202 response code and no content.

Path Parameters

autoscale_pool_id string required
Example: 0d3db13e-a604-4944-9827-7ec2642d32ac

A unique identifier for an autoscale pool.

Request: /v2/droplets/autoscale/{autoscale_pool_id}
curl -X DELETE \
  -H "Content-Type: application/json" \
  -H "Authorization: Bearer $DIGITALOCEAN_TOKEN" \
  "https://api.digitalocean.com/v2/droplets/autoscale/880fee37-d07a-4f94-94a0-f07d9fc7bbb4"

Responses

202

The action was successful and the response body is empty.
Response Headers
ratelimit-limit integer

The default limit on number of requests that can be made per hour and per minute. Current rate limits are 5000 requests per hour and 250 requests per minute.

ratelimit-remaining integer

The number of requests in your hourly quota that remain before you hit your request limit. See https://docs.digitalocean.com/reference/api/reference/#rate-limit for information about how requests expire.

ratelimit-reset integer

The time when the oldest request will expire. The value is given in Unix epoch time. See https://docs.digitalocean.com/reference/api/reference/#rate-limit for information about how requests expire.

401

Authentication failed due to invalid credentials.
Response Headers
ratelimit-limit integer

The default limit on number of requests that can be made per hour and per minute. Current rate limits are 5000 requests per hour and 250 requests per minute.

ratelimit-remaining integer

The number of requests in your hourly quota that remain before you hit your request limit. See https://docs.digitalocean.com/reference/api/reference/#rate-limit for information about how requests expire.

ratelimit-reset integer

The time when the oldest request will expire. The value is given in Unix epoch time. See https://docs.digitalocean.com/reference/api/reference/#rate-limit for information about how requests expire.

Response Schema: application/json
id string required
Example: not_found

A short identifier corresponding to the HTTP status code returned. For example, the ID for a response returning a 404 status code would be "not_found."

message string required
Example: The resource you were accessing could not be found.

A message providing additional information about the error, including details to help resolve it when possible.

request_id string optional
Example: 4d9d8375-3c56-4925-a3e7-eb137fed17e9

Optionally, some endpoints may include a request ID that should be provided when reporting bugs or opening support tickets to help identify the issue.

404

The resource was not found.
Response Headers
ratelimit-limit integer

The default limit on number of requests that can be made per hour and per minute. Current rate limits are 5000 requests per hour and 250 requests per minute.

ratelimit-remaining integer

The number of requests in your hourly quota that remain before you hit your request limit. See https://docs.digitalocean.com/reference/api/reference/#rate-limit for information about how requests expire.

ratelimit-reset integer

The time when the oldest request will expire. The value is given in Unix epoch time. See https://docs.digitalocean.com/reference/api/reference/#rate-limit for information about how requests expire.

Response Schema: application/json
id string required
Example: not_found

A short identifier corresponding to the HTTP status code returned. For example, the ID for a response returning a 404 status code would be "not_found."

message string required
Example: The resource you were accessing could not be found.

A message providing additional information about the error, including details to help resolve it when possible.

request_id string optional
Example: 4d9d8375-3c56-4925-a3e7-eb137fed17e9

Optionally, some endpoints may include a request ID that should be provided when reporting bugs or opening support tickets to help identify the issue.

429

The API rate limit has been exceeded.
Response Headers
ratelimit-limit integer

The default limit on number of requests that can be made per hour and per minute. Current rate limits are 5000 requests per hour and 250 requests per minute.

ratelimit-remaining integer

The number of requests in your hourly quota that remain before you hit your request limit. See https://docs.digitalocean.com/reference/api/reference/#rate-limit for information about how requests expire.

ratelimit-reset integer

The time when the oldest request will expire. The value is given in Unix epoch time. See https://docs.digitalocean.com/reference/api/reference/#rate-limit for information about how requests expire.

Response Schema: application/json
id string required
Example: not_found

A short identifier corresponding to the HTTP status code returned. For example, the ID for a response returning a 404 status code would be "not_found."

message string required
Example: The resource you were accessing could not be found.

A message providing additional information about the error, including details to help resolve it when possible.

request_id string optional
Example: 4d9d8375-3c56-4925-a3e7-eb137fed17e9

Optionally, some endpoints may include a request ID that should be provided when reporting bugs or opening support tickets to help identify the issue.

500

There was a server error.
Response Headers
ratelimit-limit integer

The default limit on number of requests that can be made per hour and per minute. Current rate limits are 5000 requests per hour and 250 requests per minute.

ratelimit-remaining integer

The number of requests in your hourly quota that remain before you hit your request limit. See https://docs.digitalocean.com/reference/api/reference/#rate-limit for information about how requests expire.

ratelimit-reset integer

The time when the oldest request will expire. The value is given in Unix epoch time. See https://docs.digitalocean.com/reference/api/reference/#rate-limit for information about how requests expire.

Response Schema: application/json
id string required
Example: not_found

A short identifier corresponding to the HTTP status code returned. For example, the ID for a response returning a 404 status code would be "not_found."

message string required
Example: The resource you were accessing could not be found.

A message providing additional information about the error, including details to help resolve it when possible.

request_id string optional
Example: 4d9d8375-3c56-4925-a3e7-eb137fed17e9

Optionally, some endpoints may include a request ID that should be provided when reporting bugs or opening support tickets to help identify the issue.

default

There was an unexpected error.
Response Headers
ratelimit-limit integer

The default limit on number of requests that can be made per hour and per minute. Current rate limits are 5000 requests per hour and 250 requests per minute.

ratelimit-remaining integer

The number of requests in your hourly quota that remain before you hit your request limit. See https://docs.digitalocean.com/reference/api/reference/#rate-limit for information about how requests expire.

ratelimit-reset integer

The time when the oldest request will expire. The value is given in Unix epoch time. See https://docs.digitalocean.com/reference/api/reference/#rate-limit for information about how requests expire.

Response Schema: application/json
id string required
Example: not_found

A short identifier corresponding to the HTTP status code returned. For example, the ID for a response returning a 404 status code would be "not_found."

message string required
Example: The resource you were accessing could not be found.

A message providing additional information about the error, including details to help resolve it when possible.

request_id string optional
Example: 4d9d8375-3c56-4925-a3e7-eb137fed17e9

Optionally, some endpoints may include a request ID that should be provided when reporting bugs or opening support tickets to help identify the issue.

Response
{
  "id": "unauthorized",
  "message": "Unable to authenticate you."
}
{
  "id": "not_found",
  "message": "The resource you requested could not be found."
}
{
  "id": "too_many_requests",
  "message": "API rate limit exceeded."
}
{
  "id": "server_error",
  "message": "Unexpected server-side error"
}
{
  "id": "example_error",
  "message": "some error message"
}

DELETE Delete autoscale pool and resources

/v2/droplets/autoscale/{autoscale_pool_id}/dangerous
Authorizations: bearer_auth (1 scope)
Http: Bearer
Required scopes: droplet:delete

OAuth Authentication

In order to interact with the DigitalOcean API, you or your application must authenticate.

The DigitalOcean API handles this through OAuth, an open standard for authorization. OAuth allows you to delegate access to your account. Scopes can be used to grant full access, read-only access, or access to a specific set of endpoints.

You can generate an OAuth token by visiting the Apps & API section of the DigitalOcean control panel for your account.

An OAuth token functions as a complete authentication request. In effect, it acts as a substitute for a username and password pair.

Because of this, it is absolutely essential that you keep your OAuth tokens secure. In fact, upon generation, the web interface will only display each token a single time in order to prevent the token from being compromised.

DigitalOcean access tokens begin with an identifiable prefix in order to distinguish them from other similar tokens.

  • dop_v1_ for personal access tokens generated in the control panel
  • doo_v1_ for tokens generated by applications using the OAuth flow
  • dor_v1_ for OAuth refresh tokens

Scopes

Scopes act like permissions assigned to an API token. These permissions determine what actions the token can perform. You can create API tokens that grant read-only access, full access, or limited access to specific endpoints by using custom scopes.

Generally, scopes are designed to match HTTP verbs and common CRUD operations (Create, Read, Update, Delete).

HTTP Verb CRUD Operation Scope
GET Read <resource>:read
POST Create <resource>:create
PUT/PATCH Update <resource>:update
DELETE Delete <resource>:delete

For example, creating a new Droplet by making a POST request to the /v2/droplets endpoint requires the droplet:create scope while listing Droplets by making a GET request to the /v2/droplets endpoint requires the droplet:read scope.

Each endpoint below specifies which scope is required to access it when using custom scopes.

How to Authenticate with OAuth

In order to make an authenticated request, include a bearer-type Authorization header containing your OAuth token. All requests must be made over HTTPS.

Authenticate with a Bearer Authorization Header

curl -X $HTTP_METHOD -H "Authorization: Bearer $DIGITALOCEAN_TOKEN" "https://api.digitalocean.com/v2/$OBJECT"

To destroy an autoscale pool and its associated resources (Droplets), send a DELETE request to the /v2/droplets/autoscale/$AUTOSCALE_POOL_ID/dangerous endpoint.

Path Parameters

autoscale_pool_id string required
Example: 0d3db13e-a604-4944-9827-7ec2642d32ac

A unique identifier for an autoscale pool.

Header Parameters

X-Dangerous boolean required
Example: true

Acknowledge this action will destroy the autoscale pool and its associated resources and can not be reversed.

Request: /v2/droplets/autoscale/{autoscale_pool_id}/dangerous
curl -X DELETE \
  -H "Content-Type: application/json" \
  -H "Authorization: Bearer $DIGITALOCEAN_TOKEN" \
  -H "X-Dangerous: true" \
  "https://api.digitalocean.com/v2/droplets/autoscale/880fee37-d07a-4f94-94a0-f07d9fc7bbb4/dangerous"

Responses

202

The action was successful and the response body is empty.
Response Headers
ratelimit-limit integer

The default limit on number of requests that can be made per hour and per minute. Current rate limits are 5000 requests per hour and 250 requests per minute.

ratelimit-remaining integer

The number of requests in your hourly quota that remain before you hit your request limit. See https://docs.digitalocean.com/reference/api/reference/#rate-limit for information about how requests expire.

ratelimit-reset integer

The time when the oldest request will expire. The value is given in Unix epoch time. See https://docs.digitalocean.com/reference/api/reference/#rate-limit for information about how requests expire.

401

Authentication failed due to invalid credentials.
Response Headers
ratelimit-limit integer

The default limit on number of requests that can be made per hour and per minute. Current rate limits are 5000 requests per hour and 250 requests per minute.

ratelimit-remaining integer

The number of requests in your hourly quota that remain before you hit your request limit. See https://docs.digitalocean.com/reference/api/reference/#rate-limit for information about how requests expire.

ratelimit-reset integer

The time when the oldest request will expire. The value is given in Unix epoch time. See https://docs.digitalocean.com/reference/api/reference/#rate-limit for information about how requests expire.

Response Schema: application/json
id string required
Example: not_found

A short identifier corresponding to the HTTP status code returned. For example, the ID for a response returning a 404 status code would be "not_found."

message string required
Example: The resource you were accessing could not be found.

A message providing additional information about the error, including details to help resolve it when possible.

request_id string optional
Example: 4d9d8375-3c56-4925-a3e7-eb137fed17e9

Optionally, some endpoints may include a request ID that should be provided when reporting bugs or opening support tickets to help identify the issue.

404

The resource was not found.
Response Headers
ratelimit-limit integer

The default limit on number of requests that can be made per hour and per minute. Current rate limits are 5000 requests per hour and 250 requests per minute.

ratelimit-remaining integer

The number of requests in your hourly quota that remain before you hit your request limit. See https://docs.digitalocean.com/reference/api/reference/#rate-limit for information about how requests expire.

ratelimit-reset integer

The time when the oldest request will expire. The value is given in Unix epoch time. See https://docs.digitalocean.com/reference/api/reference/#rate-limit for information about how requests expire.

Response Schema: application/json
id string required
Example: not_found

A short identifier corresponding to the HTTP status code returned. For example, the ID for a response returning a 404 status code would be "not_found."

message string required
Example: The resource you were accessing could not be found.

A message providing additional information about the error, including details to help resolve it when possible.

request_id string optional
Example: 4d9d8375-3c56-4925-a3e7-eb137fed17e9

Optionally, some endpoints may include a request ID that should be provided when reporting bugs or opening support tickets to help identify the issue.

429

The API rate limit has been exceeded.
Response Headers
ratelimit-limit integer

The default limit on number of requests that can be made per hour and per minute. Current rate limits are 5000 requests per hour and 250 requests per minute.

ratelimit-remaining integer

The number of requests in your hourly quota that remain before you hit your request limit. See https://docs.digitalocean.com/reference/api/reference/#rate-limit for information about how requests expire.

ratelimit-reset integer

The time when the oldest request will expire. The value is given in Unix epoch time. See https://docs.digitalocean.com/reference/api/reference/#rate-limit for information about how requests expire.

Response Schema: application/json
id string required
Example: not_found

A short identifier corresponding to the HTTP status code returned. For example, the ID for a response returning a 404 status code would be "not_found."

message string required
Example: The resource you were accessing could not be found.

A message providing additional information about the error, including details to help resolve it when possible.

request_id string optional
Example: 4d9d8375-3c56-4925-a3e7-eb137fed17e9

Optionally, some endpoints may include a request ID that should be provided when reporting bugs or opening support tickets to help identify the issue.

500

There was a server error.
Response Headers
ratelimit-limit integer

The default limit on number of requests that can be made per hour and per minute. Current rate limits are 5000 requests per hour and 250 requests per minute.

ratelimit-remaining integer

The number of requests in your hourly quota that remain before you hit your request limit. See https://docs.digitalocean.com/reference/api/reference/#rate-limit for information about how requests expire.

ratelimit-reset integer

The time when the oldest request will expire. The value is given in Unix epoch time. See https://docs.digitalocean.com/reference/api/reference/#rate-limit for information about how requests expire.

Response Schema: application/json
id string required
Example: not_found

A short identifier corresponding to the HTTP status code returned. For example, the ID for a response returning a 404 status code would be "not_found."

message string required
Example: The resource you were accessing could not be found.

A message providing additional information about the error, including details to help resolve it when possible.

request_id string optional
Example: 4d9d8375-3c56-4925-a3e7-eb137fed17e9

Optionally, some endpoints may include a request ID that should be provided when reporting bugs or opening support tickets to help identify the issue.

default

There was an unexpected error.
Response Headers
ratelimit-limit integer

The default limit on number of requests that can be made per hour and per minute. Current rate limits are 5000 requests per hour and 250 requests per minute.

ratelimit-remaining integer

The number of requests in your hourly quota that remain before you hit your request limit. See https://docs.digitalocean.com/reference/api/reference/#rate-limit for information about how requests expire.

ratelimit-reset integer

The time when the oldest request will expire. The value is given in Unix epoch time. See https://docs.digitalocean.com/reference/api/reference/#rate-limit for information about how requests expire.

Response Schema: application/json
id string required
Example: not_found

A short identifier corresponding to the HTTP status code returned. For example, the ID for a response returning a 404 status code would be "not_found."

message string required
Example: The resource you were accessing could not be found.

A message providing additional information about the error, including details to help resolve it when possible.

request_id string optional
Example: 4d9d8375-3c56-4925-a3e7-eb137fed17e9

Optionally, some endpoints may include a request ID that should be provided when reporting bugs or opening support tickets to help identify the issue.

Response
{
  "id": "unauthorized",
  "message": "Unable to authenticate you."
}
{
  "id": "not_found",
  "message": "The resource you requested could not be found."
}
{
  "id": "too_many_requests",
  "message": "API rate limit exceeded."
}
{
  "id": "server_error",
  "message": "Unexpected server-side error"
}
{
  "id": "example_error",
  "message": "some error message"
}

GET List history events

/v2/droplets/autoscale/{autoscale_pool_id}/history
Authorizations: bearer_auth (1 scope)
Http: Bearer
Required scopes: droplet:read

OAuth Authentication

In order to interact with the DigitalOcean API, you or your application must authenticate.

The DigitalOcean API handles this through OAuth, an open standard for authorization. OAuth allows you to delegate access to your account. Scopes can be used to grant full access, read-only access, or access to a specific set of endpoints.

You can generate an OAuth token by visiting the Apps & API section of the DigitalOcean control panel for your account.

An OAuth token functions as a complete authentication request. In effect, it acts as a substitute for a username and password pair.

Because of this, it is absolutely essential that you keep your OAuth tokens secure. In fact, upon generation, the web interface will only display each token a single time in order to prevent the token from being compromised.

DigitalOcean access tokens begin with an identifiable prefix in order to distinguish them from other similar tokens.

  • dop_v1_ for personal access tokens generated in the control panel
  • doo_v1_ for tokens generated by applications using the OAuth flow
  • dor_v1_ for OAuth refresh tokens

Scopes

Scopes act like permissions assigned to an API token. These permissions determine what actions the token can perform. You can create API tokens that grant read-only access, full access, or limited access to specific endpoints by using custom scopes.

Generally, scopes are designed to match HTTP verbs and common CRUD operations (Create, Read, Update, Delete).

HTTP Verb CRUD Operation Scope
GET Read <resource>:read
POST Create <resource>:create
PUT/PATCH Update <resource>:update
DELETE Delete <resource>:delete

For example, creating a new Droplet by making a POST request to the /v2/droplets endpoint requires the droplet:create scope while listing Droplets by making a GET request to the /v2/droplets endpoint requires the droplet:read scope.

Each endpoint below specifies which scope is required to access it when using custom scopes.

How to Authenticate with OAuth

In order to make an authenticated request, include a bearer-type Authorization header containing your OAuth token. All requests must be made over HTTPS.

Authenticate with a Bearer Authorization Header

curl -X $HTTP_METHOD -H "Authorization: Bearer $DIGITALOCEAN_TOKEN" "https://api.digitalocean.com/v2/$OBJECT"

To list all of the scaling history events of an autoscale pool, send a GET request to /v2/droplets/autoscale/$AUTOSCALE_POOL_ID/history.

The response body will be a JSON object with a key of history. This will be set to an array containing objects each representing a history event.

Path Parameters

autoscale_pool_id string required
Example: 0d3db13e-a604-4944-9827-7ec2642d32ac

A unique identifier for an autoscale pool.

Query Parameters

per_page integer 1 – 200 optional
Example: 2

Number of items returned per page

Default: 20
page integer >= 1 optional
Example: 1

Which 'page' of paginated results to return.

Default: 1
Request: /v2/droplets/autoscale/{autoscale_pool_id}/history
curl -X  GET \
  -H "Content-Type: application/json" \
  -H "Authorization: Bearer $DIGITALOCEAN_TOKEN" \
  "https://api.digitalocean.com/v2/droplets/autoscale/07445b1b-1dc1-414d-b0a7-239ac66a9148/history"

Responses

200

A JSON object with a key of history.
Response Headers
ratelimit-limit integer

The default limit on number of requests that can be made per hour and per minute. Current rate limits are 5000 requests per hour and 250 requests per minute.

ratelimit-remaining integer

The number of requests in your hourly quota that remain before you hit your request limit. See https://docs.digitalocean.com/reference/api/reference/#rate-limit for information about how requests expire.

ratelimit-reset integer

The time when the oldest request will expire. The value is given in Unix epoch time. See https://docs.digitalocean.com/reference/api/reference/#rate-limit for information about how requests expire.

Response Schema: application/json
history array of object optional
Show child properties
created_at string (date-time) required
Example: 2020-07-28T18:00:00Z

The creation time of the history event in ISO8601 combined date and time format.

current_instance_count integer required
Example: 2

The current number of Droplets in the autoscale pool.

desired_instance_count integer required
Example: 2

The target number of Droplets for the autoscale pool after the scaling event.

history_event_id string required
Example: 01936530-4471-7b86-9634-32d8fcfecbc6

The unique identifier of the history event.

reason string, one of: CONFIGURATION_CHANGE, SCALE_UP, SCALE_DOWN required
Example: CONFIGURATION_CHANGE

The reason for the scaling event.

status string, one of: in_progress, success, error required
Example: success

The status of the scaling event.

updated_at string (date-time) required
Example: 2020-07-28T18:00:00Z

The last updated time of the history event in ISO8601 combined date and time format.

links object optional
Show child properties
pages anyOf optional
One of:
Forward Links
last string optional
Example: https://api.digitalocean.com/v2/images?page=2

URI of the last page of the results.

next string optional
Example: https://api.digitalocean.com/v2/images?page=2

URI of the next page of the results.

Backward Links
first string optional
Example: https://api.digitalocean.com/v2/images?page=1

URI of the first page of the results.

prev string optional
Example: https://api.digitalocean.com/v2/images?page=1

URI of the previous page of the results.

meta object required
401

Authentication failed due to invalid credentials.
Response Headers
ratelimit-limit integer

The default limit on number of requests that can be made per hour and per minute. Current rate limits are 5000 requests per hour and 250 requests per minute.

ratelimit-remaining integer

The number of requests in your hourly quota that remain before you hit your request limit. See https://docs.digitalocean.com/reference/api/reference/#rate-limit for information about how requests expire.

ratelimit-reset integer

The time when the oldest request will expire. The value is given in Unix epoch time. See https://docs.digitalocean.com/reference/api/reference/#rate-limit for information about how requests expire.

Response Schema: application/json
id string required
Example: not_found

A short identifier corresponding to the HTTP status code returned. For example, the ID for a response returning a 404 status code would be "not_found."

message string required
Example: The resource you were accessing could not be found.

A message providing additional information about the error, including details to help resolve it when possible.

request_id string optional
Example: 4d9d8375-3c56-4925-a3e7-eb137fed17e9

Optionally, some endpoints may include a request ID that should be provided when reporting bugs or opening support tickets to help identify the issue.

404

The resource was not found.
Response Headers
ratelimit-limit integer

The default limit on number of requests that can be made per hour and per minute. Current rate limits are 5000 requests per hour and 250 requests per minute.

ratelimit-remaining integer

The number of requests in your hourly quota that remain before you hit your request limit. See https://docs.digitalocean.com/reference/api/reference/#rate-limit for information about how requests expire.

ratelimit-reset integer

The time when the oldest request will expire. The value is given in Unix epoch time. See https://docs.digitalocean.com/reference/api/reference/#rate-limit for information about how requests expire.

Response Schema: application/json
id string required
Example: not_found

A short identifier corresponding to the HTTP status code returned. For example, the ID for a response returning a 404 status code would be "not_found."

message string required
Example: The resource you were accessing could not be found.

A message providing additional information about the error, including details to help resolve it when possible.

request_id string optional
Example: 4d9d8375-3c56-4925-a3e7-eb137fed17e9

Optionally, some endpoints may include a request ID that should be provided when reporting bugs or opening support tickets to help identify the issue.

429

The API rate limit has been exceeded.
Response Headers
ratelimit-limit integer

The default limit on number of requests that can be made per hour and per minute. Current rate limits are 5000 requests per hour and 250 requests per minute.

ratelimit-remaining integer

The number of requests in your hourly quota that remain before you hit your request limit. See https://docs.digitalocean.com/reference/api/reference/#rate-limit for information about how requests expire.

ratelimit-reset integer

The time when the oldest request will expire. The value is given in Unix epoch time. See https://docs.digitalocean.com/reference/api/reference/#rate-limit for information about how requests expire.

Response Schema: application/json
id string required
Example: not_found

A short identifier corresponding to the HTTP status code returned. For example, the ID for a response returning a 404 status code would be "not_found."

message string required
Example: The resource you were accessing could not be found.

A message providing additional information about the error, including details to help resolve it when possible.

request_id string optional
Example: 4d9d8375-3c56-4925-a3e7-eb137fed17e9

Optionally, some endpoints may include a request ID that should be provided when reporting bugs or opening support tickets to help identify the issue.

500

There was a server error.
Response Headers
ratelimit-limit integer

The default limit on number of requests that can be made per hour and per minute. Current rate limits are 5000 requests per hour and 250 requests per minute.

ratelimit-remaining integer

The number of requests in your hourly quota that remain before you hit your request limit. See https://docs.digitalocean.com/reference/api/reference/#rate-limit for information about how requests expire.

ratelimit-reset integer

The time when the oldest request will expire. The value is given in Unix epoch time. See https://docs.digitalocean.com/reference/api/reference/#rate-limit for information about how requests expire.

Response Schema: application/json
id string required
Example: not_found

A short identifier corresponding to the HTTP status code returned. For example, the ID for a response returning a 404 status code would be "not_found."

message string required
Example: The resource you were accessing could not be found.

A message providing additional information about the error, including details to help resolve it when possible.

request_id string optional
Example: 4d9d8375-3c56-4925-a3e7-eb137fed17e9

Optionally, some endpoints may include a request ID that should be provided when reporting bugs or opening support tickets to help identify the issue.

default

There was an unexpected error.
Response Headers
ratelimit-limit integer

The default limit on number of requests that can be made per hour and per minute. Current rate limits are 5000 requests per hour and 250 requests per minute.

ratelimit-remaining integer

The number of requests in your hourly quota that remain before you hit your request limit. See https://docs.digitalocean.com/reference/api/reference/#rate-limit for information about how requests expire.

ratelimit-reset integer

The time when the oldest request will expire. The value is given in Unix epoch time. See https://docs.digitalocean.com/reference/api/reference/#rate-limit for information about how requests expire.

Response Schema: application/json
id string required
Example: not_found

A short identifier corresponding to the HTTP status code returned. For example, the ID for a response returning a 404 status code would be "not_found."

message string required
Example: The resource you were accessing could not be found.

A message providing additional information about the error, including details to help resolve it when possible.

request_id string optional
Example: 4d9d8375-3c56-4925-a3e7-eb137fed17e9

Optionally, some endpoints may include a request ID that should be provided when reporting bugs or opening support tickets to help identify the issue.

Response
{
  "history": [
    {
      "created_at": "2020-11-19T20:27:18Z",
      "current_instance_count": 2,
      "desired_instance_count": 2,
      "history_event_id": "01936530-4471-7b86-9634-32d8fcfecbc6",
      "reason": "CONFIGURATION_CHANGE",
      "status": "success",
      "updated_at": "2020-12-01T00:42:16Z"
    }
  ],
  "links": {
    "pages": null
  },
  "meta": {
    "total": 1
  }
}
{
  "id": "unauthorized",
  "message": "Unable to authenticate you."
}
{
  "id": "not_found",
  "message": "The resource you requested could not be found."
}
{
  "id": "too_many_requests",
  "message": "API rate limit exceeded."
}
{
  "id": "server_error",
  "message": "Unexpected server-side error"
}
{
  "id": "example_error",
  "message": "some error message"
}

GET List members

/v2/droplets/autoscale/{autoscale_pool_id}/members
Authorizations: bearer_auth (1 scope)
Http: Bearer
Required scopes: droplet:read

OAuth Authentication

In order to interact with the DigitalOcean API, you or your application must authenticate.

The DigitalOcean API handles this through OAuth, an open standard for authorization. OAuth allows you to delegate access to your account. Scopes can be used to grant full access, read-only access, or access to a specific set of endpoints.

You can generate an OAuth token by visiting the Apps & API section of the DigitalOcean control panel for your account.

An OAuth token functions as a complete authentication request. In effect, it acts as a substitute for a username and password pair.

Because of this, it is absolutely essential that you keep your OAuth tokens secure. In fact, upon generation, the web interface will only display each token a single time in order to prevent the token from being compromised.

DigitalOcean access tokens begin with an identifiable prefix in order to distinguish them from other similar tokens.

  • dop_v1_ for personal access tokens generated in the control panel
  • doo_v1_ for tokens generated by applications using the OAuth flow
  • dor_v1_ for OAuth refresh tokens

Scopes

Scopes act like permissions assigned to an API token. These permissions determine what actions the token can perform. You can create API tokens that grant read-only access, full access, or limited access to specific endpoints by using custom scopes.

Generally, scopes are designed to match HTTP verbs and common CRUD operations (Create, Read, Update, Delete).

HTTP Verb CRUD Operation Scope
GET Read <resource>:read
POST Create <resource>:create
PUT/PATCH Update <resource>:update
DELETE Delete <resource>:delete

For example, creating a new Droplet by making a POST request to the /v2/droplets endpoint requires the droplet:create scope while listing Droplets by making a GET request to the /v2/droplets endpoint requires the droplet:read scope.

Each endpoint below specifies which scope is required to access it when using custom scopes.

How to Authenticate with OAuth

In order to make an authenticated request, include a bearer-type Authorization header containing your OAuth token. All requests must be made over HTTPS.

Authenticate with a Bearer Authorization Header

curl -X $HTTP_METHOD -H "Authorization: Bearer $DIGITALOCEAN_TOKEN" "https://api.digitalocean.com/v2/$OBJECT"

To list the Droplets in an autoscale pool, send a GET request to /v2/droplets/autoscale/$AUTOSCALE_POOL_ID/members.

The response body will be a JSON object with a key of droplets. This will be set to an array containing information about each of the Droplets in the autoscale pool.

Path Parameters

autoscale_pool_id string required
Example: 0d3db13e-a604-4944-9827-7ec2642d32ac

A unique identifier for an autoscale pool.

Query Parameters

per_page integer 1 – 200 optional
Example: 2

Number of items returned per page

Default: 20
page integer >= 1 optional
Example: 1

Which 'page' of paginated results to return.

Default: 1
Request: /v2/droplets/autoscale/{autoscale_pool_id}/members
curl -X GET \
  -H "Content-Type: application/json" \
  -H "Authorization: Bearer $DIGITALOCEAN_TOKEN" \
  "https://api.digitalocean.com/v2/droplets/autoscale/d0067f19-c9bd-4d8c-b28b-e464fd1fb250/members"

Responses

200

A JSON object with a key of droplets.
Response Headers
ratelimit-limit integer

The default limit on number of requests that can be made per hour and per minute. Current rate limits are 5000 requests per hour and 250 requests per minute.

ratelimit-remaining integer

The number of requests in your hourly quota that remain before you hit your request limit. See https://docs.digitalocean.com/reference/api/reference/#rate-limit for information about how requests expire.

ratelimit-reset integer

The time when the oldest request will expire. The value is given in Unix epoch time. See https://docs.digitalocean.com/reference/api/reference/#rate-limit for information about how requests expire.

Response Schema: application/json
droplets array of object optional
Show child properties
created_at string (date-time) required
Example: 2020-07-28T18:00:00Z

The creation time of the Droplet in ISO8601 combined date and time format.

current_utilization object required
Show child properties
cpu number (float) optional
Example: 0.0007338008770232183

The CPU utilization average of the individual Droplet.

memory number (float) optional
Example: 0.3588531587713522

The memory utilization average of the individual Droplet.

droplet_id integer required
Example: 459903570

The unique identifier of the Droplet.

health_status string required
Example: active

The health status of the Droplet.

status string, one of: provisioning, active, deleting, off required
Example: active

The power status of the Droplet.

updated_at string (date-time) required
Example: 2020-07-28T18:00:00Z

The last updated time of the Droplet in ISO8601 combined date and time format.

links object optional
Show child properties
pages anyOf optional
One of:
Forward Links
last string optional
Example: https://api.digitalocean.com/v2/images?page=2

URI of the last page of the results.

next string optional
Example: https://api.digitalocean.com/v2/images?page=2

URI of the next page of the results.

Backward Links
first string optional
Example: https://api.digitalocean.com/v2/images?page=1

URI of the first page of the results.

prev string optional
Example: https://api.digitalocean.com/v2/images?page=1

URI of the previous page of the results.

meta object required
401

Authentication failed due to invalid credentials.
Response Headers
ratelimit-limit integer

The default limit on number of requests that can be made per hour and per minute. Current rate limits are 5000 requests per hour and 250 requests per minute.

ratelimit-remaining integer

The number of requests in your hourly quota that remain before you hit your request limit. See https://docs.digitalocean.com/reference/api/reference/#rate-limit for information about how requests expire.

ratelimit-reset integer

The time when the oldest request will expire. The value is given in Unix epoch time. See https://docs.digitalocean.com/reference/api/reference/#rate-limit for information about how requests expire.

Response Schema: application/json
id string required
Example: not_found

A short identifier corresponding to the HTTP status code returned. For example, the ID for a response returning a 404 status code would be "not_found."

message string required
Example: The resource you were accessing could not be found.

A message providing additional information about the error, including details to help resolve it when possible.

request_id string optional
Example: 4d9d8375-3c56-4925-a3e7-eb137fed17e9

Optionally, some endpoints may include a request ID that should be provided when reporting bugs or opening support tickets to help identify the issue.

404

The resource was not found.
Response Headers
ratelimit-limit integer

The default limit on number of requests that can be made per hour and per minute. Current rate limits are 5000 requests per hour and 250 requests per minute.

ratelimit-remaining integer

The number of requests in your hourly quota that remain before you hit your request limit. See https://docs.digitalocean.com/reference/api/reference/#rate-limit for information about how requests expire.

ratelimit-reset integer

The time when the oldest request will expire. The value is given in Unix epoch time. See https://docs.digitalocean.com/reference/api/reference/#rate-limit for information about how requests expire.

Response Schema: application/json
id string required
Example: not_found

A short identifier corresponding to the HTTP status code returned. For example, the ID for a response returning a 404 status code would be "not_found."

message string required
Example: The resource you were accessing could not be found.

A message providing additional information about the error, including details to help resolve it when possible.

request_id string optional
Example: 4d9d8375-3c56-4925-a3e7-eb137fed17e9

Optionally, some endpoints may include a request ID that should be provided when reporting bugs or opening support tickets to help identify the issue.

429

The API rate limit has been exceeded.
Response Headers
ratelimit-limit integer

The default limit on number of requests that can be made per hour and per minute. Current rate limits are 5000 requests per hour and 250 requests per minute.

ratelimit-remaining integer

The number of requests in your hourly quota that remain before you hit your request limit. See https://docs.digitalocean.com/reference/api/reference/#rate-limit for information about how requests expire.

ratelimit-reset integer

The time when the oldest request will expire. The value is given in Unix epoch time. See https://docs.digitalocean.com/reference/api/reference/#rate-limit for information about how requests expire.

Response Schema: application/json
id string required
Example: not_found

A short identifier corresponding to the HTTP status code returned. For example, the ID for a response returning a 404 status code would be "not_found."

message string required
Example: The resource you were accessing could not be found.

A message providing additional information about the error, including details to help resolve it when possible.

request_id string optional
Example: 4d9d8375-3c56-4925-a3e7-eb137fed17e9

Optionally, some endpoints may include a request ID that should be provided when reporting bugs or opening support tickets to help identify the issue.

500

There was a server error.
Response Headers
ratelimit-limit integer

The default limit on number of requests that can be made per hour and per minute. Current rate limits are 5000 requests per hour and 250 requests per minute.

ratelimit-remaining integer

The number of requests in your hourly quota that remain before you hit your request limit. See https://docs.digitalocean.com/reference/api/reference/#rate-limit for information about how requests expire.

ratelimit-reset integer

The time when the oldest request will expire. The value is given in Unix epoch time. See https://docs.digitalocean.com/reference/api/reference/#rate-limit for information about how requests expire.

Response Schema: application/json
id string required
Example: not_found

A short identifier corresponding to the HTTP status code returned. For example, the ID for a response returning a 404 status code would be "not_found."

message string required
Example: The resource you were accessing could not be found.

A message providing additional information about the error, including details to help resolve it when possible.

request_id string optional
Example: 4d9d8375-3c56-4925-a3e7-eb137fed17e9

Optionally, some endpoints may include a request ID that should be provided when reporting bugs or opening support tickets to help identify the issue.

default

There was an unexpected error.
Response Headers
ratelimit-limit integer

The default limit on number of requests that can be made per hour and per minute. Current rate limits are 5000 requests per hour and 250 requests per minute.

ratelimit-remaining integer

The number of requests in your hourly quota that remain before you hit your request limit. See https://docs.digitalocean.com/reference/api/reference/#rate-limit for information about how requests expire.

ratelimit-reset integer

The time when the oldest request will expire. The value is given in Unix epoch time. See https://docs.digitalocean.com/reference/api/reference/#rate-limit for information about how requests expire.

Response Schema: application/json
id string required
Example: not_found

A short identifier corresponding to the HTTP status code returned. For example, the ID for a response returning a 404 status code would be "not_found."

message string required
Example: The resource you were accessing could not be found.

A message providing additional information about the error, including details to help resolve it when possible.

request_id string optional
Example: 4d9d8375-3c56-4925-a3e7-eb137fed17e9

Optionally, some endpoints may include a request ID that should be provided when reporting bugs or opening support tickets to help identify the issue.

Response
{
  "droplets": [
    {
      "created_at": "2020-11-19T20:27:18Z",
      "current_utilization": {
        "cpu": 0.0007338008770232183,
        "memory": 0.3588531587713522
      },
      "droplet_id": 123456,
      "health_status": "healthy",
      "status": "active",
      "updated_at": "2020-12-01T00:42:16Z"
    }
  ],
  "links": {
    "pages": null
  },
  "meta": {
    "total": 1
  }
}
{
  "id": "unauthorized",
  "message": "Unable to authenticate you."
}
{
  "id": "not_found",
  "message": "The resource you requested could not be found."
}
{
  "id": "too_many_requests",
  "message": "API rate limit exceeded."
}
{
  "id": "server_error",
  "message": "Unexpected server-side error"
}
{
  "id": "example_error",
  "message": "some error message"
}

We can't find any results for your search.

Try using different keywords or simplifying your search terms.