DigitalOcean Insights API Reference

Last verified 23 Oct 2026

Copy page as Markdown View page as Markdown

View full API reference

The DigitalOcean Insights API provides observability resources for monitoring your infrastructure, including alert rules that evaluate metrics, notification channels that deliver alert events, read-only alert instances that record when alert rules fire, PromQL, logs, spans, and traces query interfaces, and per-resource enablement of the metrics, logs, and traces signals.

Base URL https://api.digitalocean.com

Endpoints

GET List Alert Instances GET Retrieve an Alert Instance GET List Alert Rules POST Create an Alert Rule GET Retrieve an Alert Rule PUT Update an Alert Rule DELETE Delete an Alert Rule GET List Notification Channels POST Create a Notification Channel GET Retrieve a Notification Channel PUT Update a Notification Channel DELETE Delete a Notification Channel GET Execute an instant PromQL query POST Execute an instant PromQL query GET Execute a range PromQL query POST Execute a range PromQL query GET List label names POST List label names GET List values for a label GET Find series by label selectors POST Find series by label selectors POST Search logs POST Search traces GET Retrieve an existing trace POST Search spans GET List Resource Signal Enablement GET Retrieve Resource Signal Enablement PUT Update Resource Signal Enablement

GET List Alert Instances

/v2/insights/alert-instances
Authorizations: bearer_auth (1 scope)
Http: Bearer
Required scopes: insights: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 alert instances for your account, send a GET request to /v2/insights/alert-instances. Alert instances are read-only records of alert rule firings against your resources.

Results can optionally be filtered by status, rule_id, or resource_urn.

Results are ordered by triggered_at descending (newest first). Because the list is append-only and continuously growing, offset-based pagination is best-effort: newly triggered instances may shift older rows onto subsequent pages between fetches. For stable pagination, filter by rule_id or a fixed time window on the client side.

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
status string, one of: active, resolved optional
Example: active

Optional filter. When set, only alert instances with this status are returned.

rule_id string (uuid) optional
Example: 8f3a2b1c-4d5e-6f7a-8b9c-0d1e2f3a4b5c

Optional filter. When set, only alert instances fired by the alert rule with this ID are returned.

resource_urn string optional
Example: do:droplet:12345

Optional filter. When set, only resources associated with this resource URN are returned.

Request: /v2/insights/alert-instances
curl -X GET \
  -H "Content-Type: application/json" \
  -H "Authorization: Bearer $DIGITALOCEAN_TOKEN" \
  "https://api.digitalocean.com/v2/insights/alert-instances?status=active&page=1&per_page=20"

Responses

200

The response will be a JSON object with a key called alert_instances. This will be set to an array of alert instance objects, each of which will contain the standard attributes associated with an alert instance.
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
alert_instances array of object optional
Show child properties
id string (uuid) required
Example: a1b2c3d4-e5f6-7890-abcd-ef1234567890

A unique identifier for the alert instance.

last_notified_at string (date-time) optional
Example: 2026-09-03T10:15:00Z

Time a notification was last sent for this alert instance.

last_triggered_at string (date-time) required
Example: 2026-09-03T10:45:00Z

Time the alert instance most recently fired.

resolved_at string (date-time) optional
Example: 2026-09-03T11:00:00Z

Time the alert instance resolved. Only present when status is resolved.

resource_urn string optional
Example: do:droplet:12345

URN of the DigitalOcean resource the alert fired for. May be an empty string for alerts fired on non-resource-bound signals (for example, cluster/pod/namespace-scoped Kubernetes alerts).

rule_id string (uuid) required
Example: 8f3a2b1c-4d5e-6f7a-8b9c-0d1e2f3a4b5c

ID of the alert rule that fired this alert instance.

severity string, one of: warning, critical required
Example: warning

Severity of the breached threshold.

status string, one of: active, resolved required
Example: active

Current status of the alert instance.

triggered_at string (date-time) required
Example: 2026-09-03T10:15:00Z

Time the alert instance first fired.

value number (double) required
Example: 87.5

The observed metric value that breached the threshold.

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
400

There was an error parsing the request body.
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.

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
{
  "alert_instances": [
    {
      "id": "a1b2c3d4-e5f6-7890-abcd-ef1234567890",
      "last_notified_at": "2026-09-03T10:15:00Z",
      "last_triggered_at": "2026-09-03T10:45:00Z",
      "resource_urn": "do:droplet:12345",
      "rule_id": "8f3a2b1c-4d5e-6f7a-8b9c-0d1e2f3a4b5c",
      "severity": "warning",
      "status": "active",
      "triggered_at": "2026-09-03T10:15:00Z",
      "value": 87.5
    }
  ],
  "links": {
    "pages": {}
  },
  "meta": {
    "total": 1
  }
}
{
  "id": "bad_request",
  "message": "error parsing request body",
  "request_id": "4851a473-1621-42ea-b2f9-5071c0ea8414"
}
{
  "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 Alert Instance

/v2/insights/alert-instances/{id}
Authorizations: bearer_auth (1 scope)
Http: Bearer
Required scopes: insights: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 retrieve a single alert instance, send a GET request to /v2/insights/alert-instances/{id}.

Path Parameters

id string (uuid) required
Example: a1b2c3d4-e5f6-7890-abcd-ef1234567890

A unique identifier for an alert instance.

Request: /v2/insights/alert-instances/{id}
curl -X GET \
  -H "Content-Type: application/json" \
  -H "Authorization: Bearer $DIGITALOCEAN_TOKEN" \
  "https://api.digitalocean.com/v2/insights/alert-instances/a1b2c3d4-e5f6-7890-abcd-ef1234567890"

Responses

200

The response will be a JSON object with a key called alert_instance containing the standard attributes associated with an alert instance.
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
alert_instance object required

A read-only record of an alert rule firing against a resource.

Show child properties
id string (uuid) required
Example: a1b2c3d4-e5f6-7890-abcd-ef1234567890

A unique identifier for the alert instance.

last_notified_at string (date-time) optional
Example: 2026-09-03T10:15:00Z

Time a notification was last sent for this alert instance.

last_triggered_at string (date-time) required
Example: 2026-09-03T10:45:00Z

Time the alert instance most recently fired.

resolved_at string (date-time) optional
Example: 2026-09-03T11:00:00Z

Time the alert instance resolved. Only present when status is resolved.

resource_urn string optional
Example: do:droplet:12345

URN of the DigitalOcean resource the alert fired for. May be an empty string for alerts fired on non-resource-bound signals (for example, cluster/pod/namespace-scoped Kubernetes alerts).

rule_id string (uuid) required
Example: 8f3a2b1c-4d5e-6f7a-8b9c-0d1e2f3a4b5c

ID of the alert rule that fired this alert instance.

severity string, one of: warning, critical required
Example: warning

Severity of the breached threshold.

status string, one of: active, resolved required
Example: active

Current status of the alert instance.

triggered_at string (date-time) required
Example: 2026-09-03T10:15:00Z

Time the alert instance first fired.

value number (double) required
Example: 87.5

The observed metric value that breached the threshold.

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
{
  "alert_instance": {
    "id": "a1b2c3d4-e5f6-7890-abcd-ef1234567890",
    "last_notified_at": "2026-09-02T08:00:00Z",
    "last_triggered_at": "2026-09-02T08:30:00Z",
    "resolved_at": "2026-09-02T09:00:00Z",
    "resource_urn": "do:droplet:12345",
    "rule_id": "8f3a2b1c-4d5e-6f7a-8b9c-0d1e2f3a4b5c",
    "severity": "critical",
    "status": "resolved",
    "triggered_at": "2026-09-02T08:00:00Z",
    "value": 95.2
  }
}
{
  "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 Alert Rules

/v2/insights/alert-rules
Authorizations: bearer_auth (1 scope)
Http: Bearer
Required scopes: insights: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 alert rules for your account, send a GET request to /v2/insights/alert-rules. Results are paginated with page and per_page (default 20, maximum 200). Optionally filter by resource_urn.

Query Parameters

page integer >= 1 optional
Example: 1

Which 'page' of paginated results to return.

Default: 1
per_page integer 1 – 200 optional
Example: 2

Number of items returned per page

Default: 20
resource_urn string optional
Example: do:droplet:12345

Optional filter. When set, only resources associated with this resource URN are returned.

Request: /v2/insights/alert-rules
curl -X GET \
  -H "Authorization: Bearer $DIGITALOCEAN_TOKEN" \
  "https://api.digitalocean.com/v2/insights/alert-rules?page=1&per_page=20"

Responses

200

A list of alert rules.
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
alert_rules array of object required
Show child properties
created_at string (date-time) required read-only
Example: 2026-09-03T10:00:00Z

Time the alert rule was created.

id string (uuid) required read-only
Example: a1b2c3d4-e5f6-7890-abcd-ef1234567890

A unique identifier for the alert rule.

spec object required

Spec for an Insights alert rule. On create, name, query, thresholds, and at least one notification_channels binding are required. On update, omit notification_channels to keep existing bindings; an explicit empty list is rejected.

Show child properties
condition object optional

Evaluation condition for the alert rule.

Show child properties
window string (enum) optional
Example: EVALUATION_WINDOW_5M

Time window over which the metric is evaluated. Allowed values:

  • EVALUATION_WINDOW_1M = 1m
  • EVALUATION_WINDOW_5M = 5m
  • EVALUATION_WINDOW_10M = 10m
  • EVALUATION_WINDOW_15M = 15m
  • EVALUATION_WINDOW_30M = 30m
  • EVALUATION_WINDOW_1H = 1h
name string required
Example: High CPU

A human-readable name for the alert rule.

notification_channels array of object optional

Notification channels to notify when the rule fires.

Show child properties
notification_channel_id string (uuid) required
Example: 550e8400-e29b-41d4-a716-446655440000

ID of an existing notification channel owned by the account.

notify_on array of string, one of: SEVERITY_WARNING, SEVERITY_CRITICAL optional
Example: ["SEVERITY_CRITICAL"]

Severities that trigger this channel. Allowed values:

  • SEVERITY_WARNING = warning
  • SEVERITY_CRITICAL = critical
query object required

Metrics query that the alert rule evaluates. metric must be a dotted OpenTelemetry name (for example do.droplets.cpu_utilization). Underscored Prometheus-style names are rejected. When resource_urns is omitted or empty, the rule is not scoped to specific resources.

Show child properties
filters array of object optional

Optional label filters applied to the metric series.

Additional nested properties not shown. Refer to the full API spec for details.
metric string required
Example: do.droplets.cpu_utilization

Dotted OpenTelemetry metric name to evaluate (for example do.droplets.cpu_utilization).

resource_urns array of string optional
Example: ["do:droplet:12345"]

Optional list of DigitalOcean resource URNs the rule applies to. Empty or omitted means the rule is not scoped to specific resources.

tags array of string optional
Example: ["env:prod"]

Optional resource tags used to select matching resources.

re_alert_duration string, one of: RE_ALERT_DURATION_30M, RE_ALERT_DURATION_1H, RE_ALERT_DURATION_4H, RE_ALERT_DURATION_NEVER optional
Example: RE_ALERT_DURATION_4H

Minimum wait before re-notifying a still-firing alert. Defaults to RE_ALERT_DURATION_4H on create when omitted. Allowed values:

  • RE_ALERT_DURATION_30M = 30m
  • RE_ALERT_DURATION_1H = 1h
  • RE_ALERT_DURATION_4H = 4h
  • RE_ALERT_DURATION_NEVER = never
thresholds string required

Threshold configuration for the alert rule. At least one of warning or critical must be set.

status string, one of: ALERT_RULE_STATUS_ACTIVE, ALERT_RULE_STATUS_PAUSED required read-only
Example: ALERT_RULE_STATUS_ACTIVE

Current alert rule status. Allowed values:

  • ALERT_RULE_STATUS_ACTIVE = active
  • ALERT_RULE_STATUS_PAUSED = paused
updated_at string (date-time) required read-only
Example: 2026-09-03T10:00:00Z

Time the alert rule 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
{
  "alert_rules": [
    {
      "created_at": "2026-09-03T10:00:00Z",
      "id": "a1b2c3d4-e5f6-7890-abcd-ef1234567890",
      "spec": {
        "condition": {
          "window": "EVALUATION_WINDOW_5M"
        },
        "name": "High CPU",
        "notification_channels": [
          {
            "notification_channel_id": "550e8400-e29b-41d4-a716-446655440000",
            "notify_on": [
              "SEVERITY_CRITICAL"
            ]
          }
        ],
        "query": {
          "metric": "do.droplets.cpu_utilization",
          "resource_urns": [
            "do:droplet:12345"
          ]
        },
        "re_alert_duration": "RE_ALERT_DURATION_4H",
        "thresholds": {
          "critical": 95,
          "operator": "THRESHOLD_OPERATOR_GREATER_THAN",
          "warning": 80
        }
      },
      "status": "ALERT_RULE_STATUS_PAUSED",
      "updated_at": "2026-09-03T10:30:00Z"
    }
  ],
  "links": {
    "pages": {
      "first": "https://api.digitalocean.com/v2/insights/alert-rules?page=1",
      "last": "https://api.digitalocean.com/v2/insights/alert-rules?page=1"
    }
  },
  "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 an Alert Rule

/v2/insights/alert-rules
Authorizations: bearer_auth (1 scope)
Http: Bearer
Required scopes: insights: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 an alert rule, send a POST request to /v2/insights/alert-rules with a spec containing name, query, thresholds, and at least one notification_channels binding. status defaults to ALERT_RULE_STATUS_ACTIVE when omitted. re_alert_duration defaults to RE_ALERT_DURATION_4H when omitted.

query.metric must be a dotted OpenTelemetry name such as do.droplets.cpu_utilization. Underscored Prometheus-style names are rejected with 422 Unprocessable Entity.

Request Body: application/json

spec object optional
status string, one of: ALERT_RULE_STATUS_ACTIVE, ALERT_RULE_STATUS_PAUSED optional
Example: ALERT_RULE_STATUS_ACTIVE

Desired alert rule status. Allowed values:

  • ALERT_RULE_STATUS_ACTIVE = active
  • ALERT_RULE_STATUS_PAUSED = paused
Request: /v2/insights/alert-rules
Content type application/json 
{
  "spec": {
    "condition": {
      "window": "EVALUATION_WINDOW_5M"
    },
    "name": "High CPU",
    "notification_channels": [
      {
        "notification_channel_id": "550e8400-e29b-41d4-a716-446655440000",
        "notify_on": [
          "SEVERITY_CRITICAL"
        ]
      }
    ],
    "query": {
      "metric": "do.droplets.cpu_utilization",
      "resource_urns": [
        "do:droplet:12345"
      ],
      "tags": [
        "env:prod"
      ]
    },
    "re_alert_duration": "RE_ALERT_DURATION_4H",
    "thresholds": {
      "critical": 95,
      "operator": "THRESHOLD_OPERATOR_GREATER_THAN",
      "warning": 80
    }
  }
}
curl -X POST \
  -H "Content-Type: application/json" \
  -H "Authorization: Bearer $DIGITALOCEAN_TOKEN" \
  -d '{"spec":{"name":"High CPU","query":{"metric":"do.droplets.cpu_utilization","resource_urns":["do:droplet:12345"],"tags":["env:prod"]},"condition":{"window":"EVALUATION_WINDOW_5M"},"thresholds":{"warning":80,"critical":95,"operator":"THRESHOLD_OPERATOR_GREATER_THAN"},"notification_channels":[{"notification_channel_id":"550e8400-e29b-41d4-a716-446655440000","notify_on":["SEVERITY_CRITICAL"]}],"re_alert_duration":"RE_ALERT_DURATION_4H"}}' \
  "https://api.digitalocean.com/v2/insights/alert-rules"

Responses

201

A single alert rule.
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
alert_rule object required

An Insights alert rule.

Show child properties
created_at string (date-time) required read-only
Example: 2026-09-03T10:00:00Z

Time the alert rule was created.

id string (uuid) required read-only
Example: a1b2c3d4-e5f6-7890-abcd-ef1234567890

A unique identifier for the alert rule.

spec object required

Spec for an Insights alert rule. On create, name, query, thresholds, and at least one notification_channels binding are required. On update, omit notification_channels to keep existing bindings; an explicit empty list is rejected.

Show child properties
condition object optional

Evaluation condition for the alert rule.

Show child properties
window string (enum) optional
Example: EVALUATION_WINDOW_5M

Time window over which the metric is evaluated. Allowed values:

  • EVALUATION_WINDOW_1M = 1m
  • EVALUATION_WINDOW_5M = 5m
  • EVALUATION_WINDOW_10M = 10m
  • EVALUATION_WINDOW_15M = 15m
  • EVALUATION_WINDOW_30M = 30m
  • EVALUATION_WINDOW_1H = 1h
name string required
Example: High CPU

A human-readable name for the alert rule.

notification_channels array of object optional

Notification channels to notify when the rule fires.

Show child properties
notification_channel_id string (uuid) required
Example: 550e8400-e29b-41d4-a716-446655440000

ID of an existing notification channel owned by the account.

notify_on array of string, one of: SEVERITY_WARNING, SEVERITY_CRITICAL optional
Example: ["SEVERITY_CRITICAL"]

Severities that trigger this channel. Allowed values:

  • SEVERITY_WARNING = warning
  • SEVERITY_CRITICAL = critical
query object required

Metrics query that the alert rule evaluates. metric must be a dotted OpenTelemetry name (for example do.droplets.cpu_utilization). Underscored Prometheus-style names are rejected. When resource_urns is omitted or empty, the rule is not scoped to specific resources.

Show child properties
filters array of object optional

Optional label filters applied to the metric series.

Additional nested properties not shown. Refer to the full API spec for details.
metric string required
Example: do.droplets.cpu_utilization

Dotted OpenTelemetry metric name to evaluate (for example do.droplets.cpu_utilization).

resource_urns array of string optional
Example: ["do:droplet:12345"]

Optional list of DigitalOcean resource URNs the rule applies to. Empty or omitted means the rule is not scoped to specific resources.

tags array of string optional
Example: ["env:prod"]

Optional resource tags used to select matching resources.

re_alert_duration string, one of: RE_ALERT_DURATION_30M, RE_ALERT_DURATION_1H, RE_ALERT_DURATION_4H, RE_ALERT_DURATION_NEVER optional
Example: RE_ALERT_DURATION_4H

Minimum wait before re-notifying a still-firing alert. Defaults to RE_ALERT_DURATION_4H on create when omitted. Allowed values:

  • RE_ALERT_DURATION_30M = 30m
  • RE_ALERT_DURATION_1H = 1h
  • RE_ALERT_DURATION_4H = 4h
  • RE_ALERT_DURATION_NEVER = never
thresholds string required

Threshold configuration for the alert rule. At least one of warning or critical must be set.

status string, one of: ALERT_RULE_STATUS_ACTIVE, ALERT_RULE_STATUS_PAUSED required read-only
Example: ALERT_RULE_STATUS_ACTIVE

Current alert rule status. Allowed values:

  • ALERT_RULE_STATUS_ACTIVE = active
  • ALERT_RULE_STATUS_PAUSED = paused
updated_at string (date-time) required read-only
Example: 2026-09-03T10:00:00Z

Time the alert rule was last updated.

400

There was an error parsing the request body.
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.

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.

422

Unprocessable Entity
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
{
  "alert_rule": {
    "created_at": "2026-09-03T10:00:00Z",
    "id": "a1b2c3d4-e5f6-7890-abcd-ef1234567890",
    "spec": {
      "condition": {
        "window": "EVALUATION_WINDOW_5M"
      },
      "name": "High CPU",
      "notification_channels": [
        {
          "notification_channel_id": "550e8400-e29b-41d4-a716-446655440000",
          "notify_on": [
            "SEVERITY_CRITICAL"
          ]
        }
      ],
      "query": {
        "metric": "do.droplets.cpu_utilization",
        "resource_urns": [
          "do:droplet:12345"
        ],
        "tags": [
          "env:prod"
        ]
      },
      "re_alert_duration": "RE_ALERT_DURATION_4H",
      "thresholds": {
        "critical": 95,
        "operator": "THRESHOLD_OPERATOR_GREATER_THAN",
        "warning": 80
      }
    },
    "status": "ALERT_RULE_STATUS_ACTIVE",
    "updated_at": "2026-09-03T10:00:00Z"
  }
}
{
  "id": "bad_request",
  "message": "error parsing request body",
  "request_id": "4851a473-1621-42ea-b2f9-5071c0ea8414"
}
{
  "id": "unauthorized",
  "message": "Unable to authenticate you."
}
{
  "id": "unprocessable_entity",
  "message": "request payload validation failed",
  "request_id": "4851a473-1621-42ea-b2f9-5071c0ea8414"
}
{
  "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 Alert Rule

/v2/insights/alert-rules/{id}
Authorizations: bearer_auth (1 scope)
Http: Bearer
Required scopes: insights: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 retrieve an alert rule, send a GET request to /v2/insights/alert-rules/{id}.

Path Parameters

id string (uuid) required
Example: a1b2c3d4-e5f6-7890-abcd-ef1234567890

A unique identifier for an alert rule.

Request: /v2/insights/alert-rules/{id}
curl -X GET \
  -H "Authorization: Bearer $DIGITALOCEAN_TOKEN" \
  "https://api.digitalocean.com/v2/insights/alert-rules/a1b2c3d4-e5f6-7890-abcd-ef1234567890"

Responses

200

A single alert rule.
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
alert_rule object required

An Insights alert rule.

Show child properties
created_at string (date-time) required read-only
Example: 2026-09-03T10:00:00Z

Time the alert rule was created.

id string (uuid) required read-only
Example: a1b2c3d4-e5f6-7890-abcd-ef1234567890

A unique identifier for the alert rule.

spec object required

Spec for an Insights alert rule. On create, name, query, thresholds, and at least one notification_channels binding are required. On update, omit notification_channels to keep existing bindings; an explicit empty list is rejected.

Show child properties
condition object optional

Evaluation condition for the alert rule.

Show child properties
window string (enum) optional
Example: EVALUATION_WINDOW_5M

Time window over which the metric is evaluated. Allowed values:

  • EVALUATION_WINDOW_1M = 1m
  • EVALUATION_WINDOW_5M = 5m
  • EVALUATION_WINDOW_10M = 10m
  • EVALUATION_WINDOW_15M = 15m
  • EVALUATION_WINDOW_30M = 30m
  • EVALUATION_WINDOW_1H = 1h
name string required
Example: High CPU

A human-readable name for the alert rule.

notification_channels array of object optional

Notification channels to notify when the rule fires.

Show child properties
notification_channel_id string (uuid) required
Example: 550e8400-e29b-41d4-a716-446655440000

ID of an existing notification channel owned by the account.

notify_on array of string, one of: SEVERITY_WARNING, SEVERITY_CRITICAL optional
Example: ["SEVERITY_CRITICAL"]

Severities that trigger this channel. Allowed values:

  • SEVERITY_WARNING = warning
  • SEVERITY_CRITICAL = critical
query object required

Metrics query that the alert rule evaluates. metric must be a dotted OpenTelemetry name (for example do.droplets.cpu_utilization). Underscored Prometheus-style names are rejected. When resource_urns is omitted or empty, the rule is not scoped to specific resources.

Show child properties
filters array of object optional

Optional label filters applied to the metric series.

Additional nested properties not shown. Refer to the full API spec for details.
metric string required
Example: do.droplets.cpu_utilization

Dotted OpenTelemetry metric name to evaluate (for example do.droplets.cpu_utilization).

resource_urns array of string optional
Example: ["do:droplet:12345"]

Optional list of DigitalOcean resource URNs the rule applies to. Empty or omitted means the rule is not scoped to specific resources.

tags array of string optional
Example: ["env:prod"]

Optional resource tags used to select matching resources.

re_alert_duration string, one of: RE_ALERT_DURATION_30M, RE_ALERT_DURATION_1H, RE_ALERT_DURATION_4H, RE_ALERT_DURATION_NEVER optional
Example: RE_ALERT_DURATION_4H

Minimum wait before re-notifying a still-firing alert. Defaults to RE_ALERT_DURATION_4H on create when omitted. Allowed values:

  • RE_ALERT_DURATION_30M = 30m
  • RE_ALERT_DURATION_1H = 1h
  • RE_ALERT_DURATION_4H = 4h
  • RE_ALERT_DURATION_NEVER = never
thresholds string required

Threshold configuration for the alert rule. At least one of warning or critical must be set.

status string, one of: ALERT_RULE_STATUS_ACTIVE, ALERT_RULE_STATUS_PAUSED required read-only
Example: ALERT_RULE_STATUS_ACTIVE

Current alert rule status. Allowed values:

  • ALERT_RULE_STATUS_ACTIVE = active
  • ALERT_RULE_STATUS_PAUSED = paused
updated_at string (date-time) required read-only
Example: 2026-09-03T10:00:00Z

Time the alert rule 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
{
  "alert_rule": {
    "created_at": "2026-09-03T10:00:00Z",
    "id": "a1b2c3d4-e5f6-7890-abcd-ef1234567890",
    "spec": {
      "condition": {
        "window": "EVALUATION_WINDOW_5M"
      },
      "name": "High CPU",
      "notification_channels": [
        {
          "notification_channel_id": "550e8400-e29b-41d4-a716-446655440000",
          "notify_on": [
            "SEVERITY_CRITICAL"
          ]
        }
      ],
      "query": {
        "metric": "do.droplets.cpu_utilization",
        "resource_urns": [
          "do:droplet:12345"
        ],
        "tags": [
          "env:prod"
        ]
      },
      "re_alert_duration": "RE_ALERT_DURATION_4H",
      "thresholds": {
        "critical": 95,
        "operator": "THRESHOLD_OPERATOR_GREATER_THAN",
        "warning": 80
      }
    },
    "status": "ALERT_RULE_STATUS_ACTIVE",
    "updated_at": "2026-09-03T10:00:00Z"
  }
}
{
  "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 an Alert Rule

/v2/insights/alert-rules/{id}
Authorizations: bearer_auth (1 scope)
Http: Bearer
Required scopes: insights:update

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"

This PUT endpoint uses merge semantics. To update an alert rule, send a request to /v2/insights/alert-rules/{id} with a full spec. Omit notification_channels to keep existing bindings. Omit status or re_alert_duration to keep those existing values.

Path Parameters

id string (uuid) required
Example: a1b2c3d4-e5f6-7890-abcd-ef1234567890

A unique identifier for an alert rule.

Request Body: application/json

spec object required

Spec for an Insights alert rule. On create, name, query, thresholds, and at least one notification_channels binding are required. On update, omit notification_channels to keep existing bindings; an explicit empty list is rejected.

Show child properties
condition object optional

Evaluation condition for the alert rule.

Show child properties
window string (enum) optional
Example: EVALUATION_WINDOW_5M

Time window over which the metric is evaluated. Allowed values:

  • EVALUATION_WINDOW_1M = 1m
  • EVALUATION_WINDOW_5M = 5m
  • EVALUATION_WINDOW_10M = 10m
  • EVALUATION_WINDOW_15M = 15m
  • EVALUATION_WINDOW_30M = 30m
  • EVALUATION_WINDOW_1H = 1h
name string required
Example: High CPU

A human-readable name for the alert rule.

notification_channels array of object optional

Notification channels to notify when the rule fires.

Show child properties
notification_channel_id string (uuid) required
Example: 550e8400-e29b-41d4-a716-446655440000

ID of an existing notification channel owned by the account.

notify_on array of string, one of: SEVERITY_WARNING, SEVERITY_CRITICAL optional
Example: ["SEVERITY_CRITICAL"]

Severities that trigger this channel. Allowed values:

  • SEVERITY_WARNING = warning
  • SEVERITY_CRITICAL = critical
query object required

Metrics query that the alert rule evaluates. metric must be a dotted OpenTelemetry name (for example do.droplets.cpu_utilization). Underscored Prometheus-style names are rejected. When resource_urns is omitted or empty, the rule is not scoped to specific resources.

Show child properties
filters array of object optional

Optional label filters applied to the metric series.

Show child properties
field string required
Example: host_id

The metric label or field to filter on.

operator string (enum) required
Example: FILTER_OPERATOR_EQUAL

Comparison operator for the filter. Allowed values:

  • FILTER_OPERATOR_EQUAL = equal
  • FILTER_OPERATOR_NOT_EQUAL = not_equal
  • FILTER_OPERATOR_LESS_THAN = less_than
  • FILTER_OPERATOR_LESS_THAN_OR_EQUAL = less_than_or_equal
  • FILTER_OPERATOR_GREATER_THAN = greater_than
  • FILTER_OPERATOR_GREATER_THAN_OR_EQUAL = greater_than_or_equal
value string required
Example: 12345678

Value compared against the field.

metric string required
Example: do.droplets.cpu_utilization

Dotted OpenTelemetry metric name to evaluate (for example do.droplets.cpu_utilization).

resource_urns array of string optional
Example: ["do:droplet:12345"]

Optional list of DigitalOcean resource URNs the rule applies to. Empty or omitted means the rule is not scoped to specific resources.

tags array of string optional
Example: ["env:prod"]

Optional resource tags used to select matching resources.

re_alert_duration string, one of: RE_ALERT_DURATION_30M, RE_ALERT_DURATION_1H, RE_ALERT_DURATION_4H, RE_ALERT_DURATION_NEVER optional
Example: RE_ALERT_DURATION_4H

Minimum wait before re-notifying a still-firing alert. Defaults to RE_ALERT_DURATION_4H on create when omitted. Allowed values:

  • RE_ALERT_DURATION_30M = 30m
  • RE_ALERT_DURATION_1H = 1h
  • RE_ALERT_DURATION_4H = 4h
  • RE_ALERT_DURATION_NEVER = never
thresholds string required

Threshold configuration for the alert rule. At least one of warning or critical must be set.

status string, one of: ALERT_RULE_STATUS_ACTIVE, ALERT_RULE_STATUS_PAUSED optional
Example: ALERT_RULE_STATUS_ACTIVE

Desired alert rule status. Allowed values:

  • ALERT_RULE_STATUS_ACTIVE = active
  • ALERT_RULE_STATUS_PAUSED = paused
Request: /v2/insights/alert-rules/{id}
Content type application/json 
{
  "spec": {
    "condition": {
      "window": "EVALUATION_WINDOW_15M"
    },
    "name": "High CPU (renamed)",
    "notification_channels": [
      {
        "notification_channel_id": "550e8400-e29b-41d4-a716-446655440000"
      }
    ],
    "query": {
      "metric": "do.droplets.cpu_utilization",
      "resource_urns": [
        "do:droplet:12345",
        "do:droplet:67890"
      ]
    },
    "thresholds": {
      "critical": 90,
      "operator": "THRESHOLD_OPERATOR_GREATER_THAN_OR_EQUAL"
    }
  },
  "status": "ALERT_RULE_STATUS_PAUSED"
}
curl -X PUT \
  -H "Content-Type: application/json" \
  -H "Authorization: Bearer $DIGITALOCEAN_TOKEN" \
  -d '{"spec":{"name":"High CPU (renamed)","query":{"metric":"do.droplets.cpu_utilization","resource_urns":["do:droplet:12345","do:droplet:67890"]},"condition":{"window":"EVALUATION_WINDOW_15M"},"thresholds":{"critical":90,"operator":"THRESHOLD_OPERATOR_GREATER_THAN_OR_EQUAL"},"notification_channels":[{"notification_channel_id":"550e8400-e29b-41d4-a716-446655440000"}]},"status":"ALERT_RULE_STATUS_PAUSED"}' \
  "https://api.digitalocean.com/v2/insights/alert-rules/a1b2c3d4-e5f6-7890-abcd-ef1234567890"

Responses

200

A single alert rule.
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
alert_rule object required

An Insights alert rule.

Show child properties
created_at string (date-time) required read-only
Example: 2026-09-03T10:00:00Z

Time the alert rule was created.

id string (uuid) required read-only
Example: a1b2c3d4-e5f6-7890-abcd-ef1234567890

A unique identifier for the alert rule.

spec object required

Spec for an Insights alert rule. On create, name, query, thresholds, and at least one notification_channels binding are required. On update, omit notification_channels to keep existing bindings; an explicit empty list is rejected.

Show child properties
condition object optional

Evaluation condition for the alert rule.

Show child properties
window string (enum) optional
Example: EVALUATION_WINDOW_5M

Time window over which the metric is evaluated. Allowed values:

  • EVALUATION_WINDOW_1M = 1m
  • EVALUATION_WINDOW_5M = 5m
  • EVALUATION_WINDOW_10M = 10m
  • EVALUATION_WINDOW_15M = 15m
  • EVALUATION_WINDOW_30M = 30m
  • EVALUATION_WINDOW_1H = 1h
name string required
Example: High CPU

A human-readable name for the alert rule.

notification_channels array of object optional

Notification channels to notify when the rule fires.

Show child properties
notification_channel_id string (uuid) required
Example: 550e8400-e29b-41d4-a716-446655440000

ID of an existing notification channel owned by the account.

notify_on array of string, one of: SEVERITY_WARNING, SEVERITY_CRITICAL optional
Example: ["SEVERITY_CRITICAL"]

Severities that trigger this channel. Allowed values:

  • SEVERITY_WARNING = warning
  • SEVERITY_CRITICAL = critical
query object required

Metrics query that the alert rule evaluates. metric must be a dotted OpenTelemetry name (for example do.droplets.cpu_utilization). Underscored Prometheus-style names are rejected. When resource_urns is omitted or empty, the rule is not scoped to specific resources.

Show child properties
filters array of object optional

Optional label filters applied to the metric series.

Additional nested properties not shown. Refer to the full API spec for details.
metric string required
Example: do.droplets.cpu_utilization

Dotted OpenTelemetry metric name to evaluate (for example do.droplets.cpu_utilization).

resource_urns array of string optional
Example: ["do:droplet:12345"]

Optional list of DigitalOcean resource URNs the rule applies to. Empty or omitted means the rule is not scoped to specific resources.

tags array of string optional
Example: ["env:prod"]

Optional resource tags used to select matching resources.

re_alert_duration string, one of: RE_ALERT_DURATION_30M, RE_ALERT_DURATION_1H, RE_ALERT_DURATION_4H, RE_ALERT_DURATION_NEVER optional
Example: RE_ALERT_DURATION_4H

Minimum wait before re-notifying a still-firing alert. Defaults to RE_ALERT_DURATION_4H on create when omitted. Allowed values:

  • RE_ALERT_DURATION_30M = 30m
  • RE_ALERT_DURATION_1H = 1h
  • RE_ALERT_DURATION_4H = 4h
  • RE_ALERT_DURATION_NEVER = never
thresholds string required

Threshold configuration for the alert rule. At least one of warning or critical must be set.

status string, one of: ALERT_RULE_STATUS_ACTIVE, ALERT_RULE_STATUS_PAUSED required read-only
Example: ALERT_RULE_STATUS_ACTIVE

Current alert rule status. Allowed values:

  • ALERT_RULE_STATUS_ACTIVE = active
  • ALERT_RULE_STATUS_PAUSED = paused
updated_at string (date-time) required read-only
Example: 2026-09-03T10:00:00Z

Time the alert rule was last updated.

400

There was an error parsing the request body.
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.

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.

422

Unprocessable Entity
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
{
  "alert_rule": {
    "created_at": "2026-09-03T10:00:00Z",
    "id": "a1b2c3d4-e5f6-7890-abcd-ef1234567890",
    "spec": {
      "condition": {
        "window": "EVALUATION_WINDOW_5M"
      },
      "name": "High CPU",
      "notification_channels": [
        {
          "notification_channel_id": "550e8400-e29b-41d4-a716-446655440000",
          "notify_on": [
            "SEVERITY_CRITICAL"
          ]
        }
      ],
      "query": {
        "metric": "do.droplets.cpu_utilization",
        "resource_urns": [
          "do:droplet:12345"
        ],
        "tags": [
          "env:prod"
        ]
      },
      "re_alert_duration": "RE_ALERT_DURATION_4H",
      "thresholds": {
        "critical": 95,
        "operator": "THRESHOLD_OPERATOR_GREATER_THAN",
        "warning": 80
      }
    },
    "status": "ALERT_RULE_STATUS_ACTIVE",
    "updated_at": "2026-09-03T10:00:00Z"
  }
}
{
  "id": "bad_request",
  "message": "error parsing request body",
  "request_id": "4851a473-1621-42ea-b2f9-5071c0ea8414"
}
{
  "id": "unauthorized",
  "message": "Unable to authenticate you."
}
{
  "id": "not_found",
  "message": "The resource you requested could not be found."
}
{
  "id": "unprocessable_entity",
  "message": "request payload validation failed",
  "request_id": "4851a473-1621-42ea-b2f9-5071c0ea8414"
}
{
  "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 an Alert Rule

/v2/insights/alert-rules/{id}
Authorizations: bearer_auth (1 scope)
Http: Bearer
Required scopes: insights: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 delete an alert rule, send a DELETE request to /v2/insights/alert-rules/{id}.

Path Parameters

id string (uuid) required
Example: a1b2c3d4-e5f6-7890-abcd-ef1234567890

A unique identifier for an alert rule.

Request: /v2/insights/alert-rules/{id}
curl -X DELETE \
  -H "Authorization: Bearer $DIGITALOCEAN_TOKEN" \
  "https://api.digitalocean.com/v2/insights/alert-rules/a1b2c3d4-e5f6-7890-abcd-ef1234567890"

Responses

204

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 Notification Channels

/v2/insights/notification-channels
Authorizations: bearer_auth (1 scope)
Http: Bearer
Required scopes: insights: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 notification channels for your account, send a GET request to /v2/insights/notification-channels. Results are paginated with page and per_page (default 20, maximum 200).

Query Parameters

page integer >= 1 optional
Example: 1

Which 'page' of paginated results to return.

Default: 1
per_page integer 1 – 200 optional
Example: 2

Number of items returned per page

Default: 20
Request: /v2/insights/notification-channels
curl -X GET \
  -H "Authorization: Bearer $DIGITALOCEAN_TOKEN" \
  "https://api.digitalocean.com/v2/insights/notification-channels?page=1&per_page=20"

Responses

200

A list of notification channels.
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
notification_channels array of object required
Show child properties
channel_type string, one of: CHANNEL_TYPE_EMAIL, CHANNEL_TYPE_SLACK, CHANNEL_TYPE_WEBHOOK required read-only
Example: CHANNEL_TYPE_EMAIL

The configured channel type. Allowed values:

  • CHANNEL_TYPE_EMAIL = email
  • CHANNEL_TYPE_SLACK = slack
  • CHANNEL_TYPE_WEBHOOK = webhook
created_at string (date-time) required read-only
Example: 2026-09-03T10:15:00Z

Time the notification channel was created.

email object optional

Email notification channel configuration. Recipients must be verified team member email addresses.

Show child properties
to string required
Example: [email protected], [email protected]

One or more recipient email addresses, separated by commas, semicolons, or spaces.

id string (uuid) required read-only
Example: 550e8400-e29b-41d4-a716-446655440000

A unique identifier for the notification channel.

name string required
Example: On-call email

A human-readable name for the notification channel.

slack object optional

Slack notification channel configuration as returned in API responses. The webhook URL is never returned; webhook_url_status indicates whether it is configured.

Show child properties
channel string required
Example: #platform-alerts

The Slack channel name to notify.

webhook_url_status object optional

Present when a Slack webhook URL is configured. Omitted when not configured.

updated_at string (date-time) required read-only
Example: 2026-09-03T10:15:00Z

Time the notification channel was last updated.

usage object optional read-only
webhook object optional

Generic HTTPS webhook notification channel configuration as returned in API responses. The URL and headers are returned in full. Credential secrets are never returned; nested *_status objects indicate whether they are configured.

Show child properties
basic_auth object optional

HTTP basic authentication as returned in API responses. The password is never returned; password_status indicates whether it is configured.

Show child properties
password_status object optional

Present when a basic auth password is configured. Omitted when not configured.

username string required
Example: webhook-user

Basic auth username.

bearer_token object optional

Bearer token authentication as returned in API responses. The token is never returned; token_status indicates whether it is configured.

Show child properties
token_status object optional

Present when a bearer token is configured. Omitted when not configured.

headers object optional
Example: {"X-Custom":"1"}

Optional custom HTTP headers included on webhook deliveries. At most 20 headers are allowed.

signature object optional

HMAC signature configuration as returned in API responses. The signing secret is never returned; secret_status indicates whether it is configured.

Show child properties
secret_status object optional

Present when a signing secret is configured. Omitted when not configured.

url string (uri) required
Example: https://example.com/hook

HTTPS URL that receives webhook deliveries.

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
{
  "links": {
    "pages": {
      "first": "https://api.digitalocean.com/v2/insights/notification-channels?page=1",
      "last": "https://api.digitalocean.com/v2/insights/notification-channels?page=1"
    }
  },
  "meta": {
    "total": 1
  },
  "notification_channels": [
    {
      "channel_type": "CHANNEL_TYPE_EMAIL",
      "created_at": "2026-09-03T10:15:00Z",
      "email": {
        "to": "[email protected]"
      },
      "id": "550e8400-e29b-41d4-a716-446655440000",
      "name": "On-call email",
      "updated_at": "2026-09-03T10:15:00Z",
      "usage": {
        "rule_count": 2
      }
    }
  ]
}
{
  "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 Notification Channel

/v2/insights/notification-channels
Authorizations: bearer_auth (1 scope)
Http: Bearer
Required scopes: insights: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 notification channel, send a POST request to /v2/insights/notification-channels with a name and exactly one of email, slack, or webhook.

Email recipients must be verified team member addresses. Webhook URLs must use HTTPS. Secret fields (slack.webhook_url, webhook credentials) are write-only. Subsequent reads never return secret values; they include optional *_status objects when a secret is configured.

Request Body: application/json

Request: /v2/insights/notification-channels
Content type application/json
Example 
{
  "email": {
    "to": "[email protected], [email protected]"
  },
  "name": "On-call email"
}
curl -X POST \
  -H "Content-Type: application/json" \
  -H "Authorization: Bearer $DIGITALOCEAN_TOKEN" \
  -d '{"name":"Platform alerts","slack":{"webhook_url":"https://hooks.slack.com/services/T000/B000/XXXXXXXX","channel":"#platform-alerts"}}' \
  "https://api.digitalocean.com/v2/insights/notification-channels"

Responses

201

A single notification channel.
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
notification_channel object required

A reusable Insights notification channel.

Show child properties
channel_type string, one of: CHANNEL_TYPE_EMAIL, CHANNEL_TYPE_SLACK, CHANNEL_TYPE_WEBHOOK required read-only
Example: CHANNEL_TYPE_EMAIL

The configured channel type. Allowed values:

  • CHANNEL_TYPE_EMAIL = email
  • CHANNEL_TYPE_SLACK = slack
  • CHANNEL_TYPE_WEBHOOK = webhook
created_at string (date-time) required read-only
Example: 2026-09-03T10:15:00Z

Time the notification channel was created.

email object optional

Email notification channel configuration. Recipients must be verified team member email addresses.

Show child properties
to string required
Example: [email protected], [email protected]

One or more recipient email addresses, separated by commas, semicolons, or spaces.

id string (uuid) required read-only
Example: 550e8400-e29b-41d4-a716-446655440000

A unique identifier for the notification channel.

name string required
Example: On-call email

A human-readable name for the notification channel.

slack object optional

Slack notification channel configuration as returned in API responses. The webhook URL is never returned; webhook_url_status indicates whether it is configured.

Show child properties
channel string required
Example: #platform-alerts

The Slack channel name to notify.

webhook_url_status object optional

Present when a Slack webhook URL is configured. Omitted when not configured.

updated_at string (date-time) required read-only
Example: 2026-09-03T10:15:00Z

Time the notification channel was last updated.

usage object optional read-only
webhook object optional

Generic HTTPS webhook notification channel configuration as returned in API responses. The URL and headers are returned in full. Credential secrets are never returned; nested *_status objects indicate whether they are configured.

Show child properties
basic_auth object optional

HTTP basic authentication as returned in API responses. The password is never returned; password_status indicates whether it is configured.

Show child properties
password_status object optional

Present when a basic auth password is configured. Omitted when not configured.

username string required
Example: webhook-user

Basic auth username.

bearer_token object optional

Bearer token authentication as returned in API responses. The token is never returned; token_status indicates whether it is configured.

Show child properties
token_status object optional

Present when a bearer token is configured. Omitted when not configured.

headers object optional
Example: {"X-Custom":"1"}

Optional custom HTTP headers included on webhook deliveries. At most 20 headers are allowed.

signature object optional

HMAC signature configuration as returned in API responses. The signing secret is never returned; secret_status indicates whether it is configured.

Show child properties
secret_status object optional

Present when a signing secret is configured. Omitted when not configured.

url string (uri) required
Example: https://example.com/hook

HTTPS URL that receives webhook deliveries.

400

There was an error parsing the request body.
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.

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 
{
  "notification_channel": {
    "channel_type": "CHANNEL_TYPE_EMAIL",
    "created_at": "2026-09-03T10:15:00Z",
    "email": {
      "to": "[email protected], [email protected]"
    },
    "id": "550e8400-e29b-41d4-a716-446655440000",
    "name": "On-call email",
    "updated_at": "2026-09-03T10:15:00Z",
    "usage": {
      "rule_count": 0
    }
  }
}
{
  "id": "bad_request",
  "message": "error parsing request body",
  "request_id": "4851a473-1621-42ea-b2f9-5071c0ea8414"
}
{
  "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 a Notification Channel

/v2/insights/notification-channels/{id}
Authorizations: bearer_auth (1 scope)
Http: Bearer
Required scopes: insights: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 retrieve a notification channel, send a GET request to /v2/insights/notification-channels/{id}. Secret credentials are never returned. When a secret is configured, the response includes an optional *_status object (for example webhook_url_status) with configured: true.

Path Parameters

id string (uuid) required
Example: 550e8400-e29b-41d4-a716-446655440000

A unique identifier for a notification channel.

Request: /v2/insights/notification-channels/{id}
curl -X GET \
  -H "Authorization: Bearer $DIGITALOCEAN_TOKEN" \
  "https://api.digitalocean.com/v2/insights/notification-channels/550e8400-e29b-41d4-a716-446655440000"

Responses

200

A single notification channel.
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
notification_channel object required

A reusable Insights notification channel.

Show child properties
channel_type string, one of: CHANNEL_TYPE_EMAIL, CHANNEL_TYPE_SLACK, CHANNEL_TYPE_WEBHOOK required read-only
Example: CHANNEL_TYPE_EMAIL

The configured channel type. Allowed values:

  • CHANNEL_TYPE_EMAIL = email
  • CHANNEL_TYPE_SLACK = slack
  • CHANNEL_TYPE_WEBHOOK = webhook
created_at string (date-time) required read-only
Example: 2026-09-03T10:15:00Z

Time the notification channel was created.

email object optional

Email notification channel configuration. Recipients must be verified team member email addresses.

Show child properties
to string required
Example: [email protected], [email protected]

One or more recipient email addresses, separated by commas, semicolons, or spaces.

id string (uuid) required read-only
Example: 550e8400-e29b-41d4-a716-446655440000

A unique identifier for the notification channel.

name string required
Example: On-call email

A human-readable name for the notification channel.

slack object optional

Slack notification channel configuration as returned in API responses. The webhook URL is never returned; webhook_url_status indicates whether it is configured.

Show child properties
channel string required
Example: #platform-alerts

The Slack channel name to notify.

webhook_url_status object optional

Present when a Slack webhook URL is configured. Omitted when not configured.

updated_at string (date-time) required read-only
Example: 2026-09-03T10:15:00Z

Time the notification channel was last updated.

usage object optional read-only
webhook object optional

Generic HTTPS webhook notification channel configuration as returned in API responses. The URL and headers are returned in full. Credential secrets are never returned; nested *_status objects indicate whether they are configured.

Show child properties
basic_auth object optional

HTTP basic authentication as returned in API responses. The password is never returned; password_status indicates whether it is configured.

Show child properties
password_status object optional

Present when a basic auth password is configured. Omitted when not configured.

username string required
Example: webhook-user

Basic auth username.

bearer_token object optional

Bearer token authentication as returned in API responses. The token is never returned; token_status indicates whether it is configured.

Show child properties
token_status object optional

Present when a bearer token is configured. Omitted when not configured.

headers object optional
Example: {"X-Custom":"1"}

Optional custom HTTP headers included on webhook deliveries. At most 20 headers are allowed.

signature object optional

HMAC signature configuration as returned in API responses. The signing secret is never returned; secret_status indicates whether it is configured.

Show child properties
secret_status object optional

Present when a signing secret is configured. Omitted when not configured.

url string (uri) required
Example: https://example.com/hook

HTTPS URL that receives webhook deliveries.

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 
{
  "notification_channel": {
    "channel_type": "CHANNEL_TYPE_EMAIL",
    "created_at": "2026-09-03T10:15:00Z",
    "email": {
      "to": "[email protected], [email protected]"
    },
    "id": "550e8400-e29b-41d4-a716-446655440000",
    "name": "On-call email",
    "updated_at": "2026-09-03T10:15:00Z",
    "usage": {
      "rule_count": 0
    }
  }
}
{
  "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 a Notification Channel

/v2/insights/notification-channels/{id}
Authorizations: bearer_auth (1 scope)
Http: Bearer
Required scopes: insights:update

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 a notification channel, send a PUT request to /v2/insights/notification-channels/{id} with a name and exactly one of email, slack, or webhook.

Sending a secret field rotates it; omitting the secret field keeps the existing value. Responses never return secret values; they include optional *_status objects when a secret is configured.

Path Parameters

id string (uuid) required
Example: 550e8400-e29b-41d4-a716-446655440000

A unique identifier for a notification channel.

Request Body: application/json

Request: /v2/insights/notification-channels/{id}
Content type application/json
Example 
{
  "name": "Platform alerts (updated)",
  "slack": {
    "channel": "#platform-alerts-prod"
  }
}
curl -X PUT \
  -H "Content-Type: application/json" \
  -H "Authorization: Bearer $DIGITALOCEAN_TOKEN" \
  -d '{"name":"Platform alerts (updated)","slack":{"channel":"#platform-alerts-prod"}}' \
  "https://api.digitalocean.com/v2/insights/notification-channels/550e8400-e29b-41d4-a716-446655440000"

Responses

200

A single notification channel.
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
notification_channel object required

A reusable Insights notification channel.

Show child properties
channel_type string, one of: CHANNEL_TYPE_EMAIL, CHANNEL_TYPE_SLACK, CHANNEL_TYPE_WEBHOOK required read-only
Example: CHANNEL_TYPE_EMAIL

The configured channel type. Allowed values:

  • CHANNEL_TYPE_EMAIL = email
  • CHANNEL_TYPE_SLACK = slack
  • CHANNEL_TYPE_WEBHOOK = webhook
created_at string (date-time) required read-only
Example: 2026-09-03T10:15:00Z

Time the notification channel was created.

email object optional

Email notification channel configuration. Recipients must be verified team member email addresses.

Show child properties
to string required
Example: [email protected], [email protected]

One or more recipient email addresses, separated by commas, semicolons, or spaces.

id string (uuid) required read-only
Example: 550e8400-e29b-41d4-a716-446655440000

A unique identifier for the notification channel.

name string required
Example: On-call email

A human-readable name for the notification channel.

slack object optional

Slack notification channel configuration as returned in API responses. The webhook URL is never returned; webhook_url_status indicates whether it is configured.

Show child properties
channel string required
Example: #platform-alerts

The Slack channel name to notify.

webhook_url_status object optional

Present when a Slack webhook URL is configured. Omitted when not configured.

updated_at string (date-time) required read-only
Example: 2026-09-03T10:15:00Z

Time the notification channel was last updated.

usage object optional read-only
webhook object optional

Generic HTTPS webhook notification channel configuration as returned in API responses. The URL and headers are returned in full. Credential secrets are never returned; nested *_status objects indicate whether they are configured.

Show child properties
basic_auth object optional

HTTP basic authentication as returned in API responses. The password is never returned; password_status indicates whether it is configured.

Show child properties
password_status object optional

Present when a basic auth password is configured. Omitted when not configured.

username string required
Example: webhook-user

Basic auth username.

bearer_token object optional

Bearer token authentication as returned in API responses. The token is never returned; token_status indicates whether it is configured.

Show child properties
token_status object optional

Present when a bearer token is configured. Omitted when not configured.

headers object optional
Example: {"X-Custom":"1"}

Optional custom HTTP headers included on webhook deliveries. At most 20 headers are allowed.

signature object optional

HMAC signature configuration as returned in API responses. The signing secret is never returned; secret_status indicates whether it is configured.

Show child properties
secret_status object optional

Present when a signing secret is configured. Omitted when not configured.

url string (uri) required
Example: https://example.com/hook

HTTPS URL that receives webhook deliveries.

400

There was an error parsing the request body.
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.

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 
{
  "notification_channel": {
    "channel_type": "CHANNEL_TYPE_EMAIL",
    "created_at": "2026-09-03T10:15:00Z",
    "email": {
      "to": "[email protected], [email protected]"
    },
    "id": "550e8400-e29b-41d4-a716-446655440000",
    "name": "On-call email",
    "updated_at": "2026-09-03T10:15:00Z",
    "usage": {
      "rule_count": 0
    }
  }
}
{
  "id": "bad_request",
  "message": "error parsing request body",
  "request_id": "4851a473-1621-42ea-b2f9-5071c0ea8414"
}
{
  "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 a Notification Channel

/v2/insights/notification-channels/{id}
Authorizations: bearer_auth (1 scope)
Http: Bearer
Required scopes: insights: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 delete a notification channel, send a DELETE request to /v2/insights/notification-channels/{id}.

Deleting a channel that is still referenced by one or more alert rules returns 409 Conflict.

Path Parameters

id string (uuid) required
Example: 550e8400-e29b-41d4-a716-446655440000

A unique identifier for a notification channel.

Request: /v2/insights/notification-channels/{id}
curl -X DELETE \
  -H "Authorization: Bearer $DIGITALOCEAN_TOKEN" \
  "https://api.digitalocean.com/v2/insights/notification-channels/550e8400-e29b-41d4-a716-446655440000"

Responses

204

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.

409

The request could not be completed due to a conflict.
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": "conflict",
  "message": "The request could not be completed due to a conflict."
}
{
  "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 Execute an instant PromQL query

/v2/insights/query/{region}/prom/api/v1/query
Authorizations: bearer_auth (1 scope)
Http: Bearer
Required scopes: insights: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 evaluate a PromQL expression at a single point in time, send a GET request to /v2/insights/query/{region}/prom/api/v1/query.

Path Parameters

region string required
Example: nyc3

The datacenter region slug for the query.

Query Parameters

query string required
Example: do.droplets.cpu_time

A PromQL expression. This may be a metric selector (for example do.droplets.cpu_time) or a fuller expression (for example rate(do.droplets.cpu_time[5m])).

time string optional
Example: 1620683817

Evaluation timestamp for an instant query. Accepts a RFC3339 string or a UNIX timestamp. Defaults to now when omitted.

timeout string optional
Example: 30s

Optional evaluation timeout as a Prometheus duration string.

Request: /v2/insights/query/{region}/prom/api/v1/query
curl -X GET \
  -H "Authorization: Bearer $DIGITALOCEAN_TOKEN" \
  --get "https://api.digitalocean.com/v2/insights/query/nyc3/prom/api/v1/query" \
  --data-urlencode "query=do.droplets.cpu_time"

Responses

200

Instant query result.
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
data object required
Show child properties
result anyOf required
Example: [{"metric":{"__name__":"do_droplets_cpu_time"},"value":[1620683817,"1"]}]

Result payload shape depends on resultType. vector and matrix are series arrays. scalar and string both use a [timestamp, value] sample pair.

resultType string, one of: vector, matrix, scalar, string required
Example: vector
status string, one of: success required
Example: success
400

Prometheus-style query 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
error string required
Example: missing query parameter

Human-readable error message.

errorType string (enum) required
Example: bad_data

Prometheus error category.

status string, one of: error required
Example: error
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.

403

The authenticated principal does not have permission to perform this action on the requested resource.
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.

422

Prometheus-style query 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
error string required
Example: missing query parameter

Human-readable error message.

errorType string (enum) required
Example: bad_data

Prometheus error category.

status string, one of: error required
Example: error
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

Prometheus-style query 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
error string required
Example: missing query parameter

Human-readable error message.

errorType string (enum) required
Example: bad_data

Prometheus error category.

status string, one of: error required
Example: error
503

Prometheus-style query 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
error string required
Example: missing query parameter

Human-readable error message.

errorType string (enum) required
Example: bad_data

Prometheus error category.

status string, one of: error required
Example: error
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
{
  "data": {
    "result": [
      {
        "metric": {
          "__name__": "do_droplets_cpu_time"
        },
        "value": [
          1620683817,
          "1"
        ]
      }
    ],
    "resultType": "vector"
  },
  "status": "success"
}
{
  "error": "missing query parameter",
  "errorType": "bad_data",
  "status": "error"
}
{
  "id": "unauthorized",
  "message": "Unable to authenticate you."
}
{
  "id": "forbidden",
  "message": "You do not have permission to perform this action."
}
{
  "id": "not_found",
  "message": "The resource you requested could not be found."
}
{
  "error": "missing query parameter",
  "errorType": "bad_data",
  "status": "error"
}
{
  "id": "too_many_requests",
  "message": "API rate limit exceeded."
}
{
  "error": "missing query parameter",
  "errorType": "bad_data",
  "status": "error"
}
{
  "error": "missing query parameter",
  "errorType": "bad_data",
  "status": "error"
}
{
  "id": "example_error",
  "message": "some error message"
}

POST Execute an instant PromQL query

/v2/insights/query/{region}/prom/api/v1/query
Authorizations: bearer_auth (1 scope)
Http: Bearer
Required scopes: insights: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 evaluate a PromQL expression at a single point in time, send a POST request to /v2/insights/query/{region}/prom/api/v1/query with application/x-www-form-urlencoded parameters.

Path Parameters

region string required
Example: nyc3

The datacenter region slug for the query.

Request Body: application/x-www-form-urlencoded

query string required
Example: do.droplets.cpu_time

A PromQL expression to evaluate.

time string optional
Example: 1620683817

Evaluation timestamp. RFC3339 or UNIX timestamp.

timeout string optional
Example: 30s

Optional evaluation timeout duration.

Request: /v2/insights/query/{region}/prom/api/v1/query
Content type application/x-www-form-urlencoded 
{
  "query": "do.droplets.cpu_time",
  "time": "1620683817",
  "timeout": "30s"
}
curl -X POST \
  -H "Authorization: Bearer $DIGITALOCEAN_TOKEN" \
  -H "Content-Type: application/x-www-form-urlencoded" \
  -d "query=do.droplets.cpu_time" \
  "https://api.digitalocean.com/v2/insights/query/nyc3/prom/api/v1/query"

Responses

200

Instant query result.
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
data object required
Show child properties
result anyOf required
Example: [{"metric":{"__name__":"do_droplets_cpu_time"},"value":[1620683817,"1"]}]

Result payload shape depends on resultType. vector and matrix are series arrays. scalar and string both use a [timestamp, value] sample pair.

resultType string, one of: vector, matrix, scalar, string required
Example: vector
status string, one of: success required
Example: success
400

Prometheus-style query 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
error string required
Example: missing query parameter

Human-readable error message.

errorType string (enum) required
Example: bad_data

Prometheus error category.

status string, one of: error required
Example: error
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.

403

The authenticated principal does not have permission to perform this action on the requested resource.
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.

422

Prometheus-style query 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
error string required
Example: missing query parameter

Human-readable error message.

errorType string (enum) required
Example: bad_data

Prometheus error category.

status string, one of: error required
Example: error
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

Prometheus-style query 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
error string required
Example: missing query parameter

Human-readable error message.

errorType string (enum) required
Example: bad_data

Prometheus error category.

status string, one of: error required
Example: error
503

Prometheus-style query 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
error string required
Example: missing query parameter

Human-readable error message.

errorType string (enum) required
Example: bad_data

Prometheus error category.

status string, one of: error required
Example: error
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
{
  "data": {
    "result": [
      {
        "metric": {
          "__name__": "do_droplets_cpu_time"
        },
        "value": [
          1620683817,
          "1"
        ]
      }
    ],
    "resultType": "vector"
  },
  "status": "success"
}
{
  "error": "missing query parameter",
  "errorType": "bad_data",
  "status": "error"
}
{
  "id": "unauthorized",
  "message": "Unable to authenticate you."
}
{
  "id": "forbidden",
  "message": "You do not have permission to perform this action."
}
{
  "id": "not_found",
  "message": "The resource you requested could not be found."
}
{
  "error": "missing query parameter",
  "errorType": "bad_data",
  "status": "error"
}
{
  "id": "too_many_requests",
  "message": "API rate limit exceeded."
}
{
  "error": "missing query parameter",
  "errorType": "bad_data",
  "status": "error"
}
{
  "error": "missing query parameter",
  "errorType": "bad_data",
  "status": "error"
}
{
  "id": "example_error",
  "message": "some error message"
}

GET Execute a range PromQL query

/v2/insights/query/{region}/prom/api/v1/query_range
Authorizations: bearer_auth (1 scope)
Http: Bearer
Required scopes: insights: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 evaluate a PromQL expression over a time range, send a GET request to /v2/insights/query/{region}/prom/api/v1/query_range.

Path Parameters

region string required
Example: nyc3

The datacenter region slug for the query.

Query Parameters

query string required
Example: do.droplets.cpu_time

A PromQL expression. This may be a metric selector (for example do.droplets.cpu_time) or a fuller expression (for example rate(do.droplets.cpu_time[5m])).

start string required
Example: 1620683817

Start timestamp (inclusive). Accepts a RFC3339 string or a UNIX timestamp.

end string required
Example: 1620705417

End timestamp (inclusive). Accepts a RFC3339 string or a UNIX timestamp.

step string required
Example: 15s

Query resolution step width as a Prometheus duration string (for example 15s, 1m, 1h).

timeout string optional
Example: 30s

Optional evaluation timeout as a Prometheus duration string.

Request: /v2/insights/query/{region}/prom/api/v1/query_range
curl -X GET \
  -H "Authorization: Bearer $DIGITALOCEAN_TOKEN" \
  --get "https://api.digitalocean.com/v2/insights/query/nyc3/prom/api/v1/query_range" \
  --data-urlencode "query=do.droplets.cpu_time" \
  --data-urlencode "start=1620683817" \
  --data-urlencode "end=1620705417" \
  --data-urlencode "step=15s"

Responses

200

Range query result.
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
data object required
Show child properties
result array of object required
Example: [{"metric":{"__name__":"do_droplets_cpu_time"},"values":[[1620683817,"1"],[1620683832,"1"]]}]

One entry per matching series, each carrying the samples evaluated at every step across the requested range.

Show child properties
metric object required
Example: {"__name__":"do_droplets_cpu_time"}

Metric labels as key/value pairs. By default, metric names in responses use Prometheus underscored spelling (for example do_droplets_cpu_time), even when the request used a dotted selector (for example do.droplets.cpu_time).

values array of array of oneOf required
resultType string, one of: matrix required
Example: matrix
status string, one of: success required
Example: success
400

Prometheus-style query 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
error string required
Example: missing query parameter

Human-readable error message.

errorType string (enum) required
Example: bad_data

Prometheus error category.

status string, one of: error required
Example: error
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.

403

The authenticated principal does not have permission to perform this action on the requested resource.
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.

422

Prometheus-style query 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
error string required
Example: missing query parameter

Human-readable error message.

errorType string (enum) required
Example: bad_data

Prometheus error category.

status string, one of: error required
Example: error
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

Prometheus-style query 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
error string required
Example: missing query parameter

Human-readable error message.

errorType string (enum) required
Example: bad_data

Prometheus error category.

status string, one of: error required
Example: error
503

Prometheus-style query 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
error string required
Example: missing query parameter

Human-readable error message.

errorType string (enum) required
Example: bad_data

Prometheus error category.

status string, one of: error required
Example: error
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
{
  "data": {
    "result": [
      {
        "metric": {
          "__name__": "do_droplets_cpu_time"
        },
        "values": [
          [
            1620683817,
            "1"
          ],
          [
            1620683832,
            "1"
          ]
        ]
      }
    ],
    "resultType": "matrix"
  },
  "status": "success"
}
{
  "error": "missing query parameter",
  "errorType": "bad_data",
  "status": "error"
}
{
  "id": "unauthorized",
  "message": "Unable to authenticate you."
}
{
  "id": "forbidden",
  "message": "You do not have permission to perform this action."
}
{
  "id": "not_found",
  "message": "The resource you requested could not be found."
}
{
  "error": "missing query parameter",
  "errorType": "bad_data",
  "status": "error"
}
{
  "id": "too_many_requests",
  "message": "API rate limit exceeded."
}
{
  "error": "missing query parameter",
  "errorType": "bad_data",
  "status": "error"
}
{
  "error": "missing query parameter",
  "errorType": "bad_data",
  "status": "error"
}
{
  "id": "example_error",
  "message": "some error message"
}

POST Execute a range PromQL query

/v2/insights/query/{region}/prom/api/v1/query_range
Authorizations: bearer_auth (1 scope)
Http: Bearer
Required scopes: insights: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 evaluate a PromQL expression over a time range, send a POST request to /v2/insights/query/{region}/prom/api/v1/query_range with application/x-www-form-urlencoded parameters.

Path Parameters

region string required
Example: nyc3

The datacenter region slug for the query.

Request Body: application/x-www-form-urlencoded

end string required
Example: 1620705417

End timestamp. RFC3339 or UNIX timestamp.

query string required
Example: do.droplets.cpu_time

A PromQL expression to evaluate.

start string required
Example: 1620683817

Start timestamp. RFC3339 or UNIX timestamp.

step string required
Example: 15s

Query resolution step width.

timeout string optional
Example: 30s

Optional evaluation timeout duration.

Request: /v2/insights/query/{region}/prom/api/v1/query_range
Content type application/x-www-form-urlencoded 
{
  "end": "1620705417",
  "query": "do.droplets.cpu_time",
  "start": "1620683817",
  "step": "15s",
  "timeout": "30s"
}
curl -X POST \
  -H "Authorization: Bearer $DIGITALOCEAN_TOKEN" \
  -H "Content-Type: application/x-www-form-urlencoded" \
  -d "query=do.droplets.cpu_time" \
  -d "start=1620683817" \
  -d "end=1620705417" \
  -d "step=15s" \
  "https://api.digitalocean.com/v2/insights/query/nyc3/prom/api/v1/query_range"

Responses

200

Range query result.
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
data object required
Show child properties
result array of object required
Example: [{"metric":{"__name__":"do_droplets_cpu_time"},"values":[[1620683817,"1"],[1620683832,"1"]]}]

One entry per matching series, each carrying the samples evaluated at every step across the requested range.

Show child properties
metric object required
Example: {"__name__":"do_droplets_cpu_time"}

Metric labels as key/value pairs. By default, metric names in responses use Prometheus underscored spelling (for example do_droplets_cpu_time), even when the request used a dotted selector (for example do.droplets.cpu_time).

values array of array of oneOf required
resultType string, one of: matrix required
Example: matrix
status string, one of: success required
Example: success
400

Prometheus-style query 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
error string required
Example: missing query parameter

Human-readable error message.

errorType string (enum) required
Example: bad_data

Prometheus error category.

status string, one of: error required
Example: error
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.

403

The authenticated principal does not have permission to perform this action on the requested resource.
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.

422

Prometheus-style query 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
error string required
Example: missing query parameter

Human-readable error message.

errorType string (enum) required
Example: bad_data

Prometheus error category.

status string, one of: error required
Example: error
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

Prometheus-style query 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
error string required
Example: missing query parameter

Human-readable error message.

errorType string (enum) required
Example: bad_data

Prometheus error category.

status string, one of: error required
Example: error
503

Prometheus-style query 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
error string required
Example: missing query parameter

Human-readable error message.

errorType string (enum) required
Example: bad_data

Prometheus error category.

status string, one of: error required
Example: error
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
{
  "data": {
    "result": [
      {
        "metric": {
          "__name__": "do_droplets_cpu_time"
        },
        "values": [
          [
            1620683817,
            "1"
          ],
          [
            1620683832,
            "1"
          ]
        ]
      }
    ],
    "resultType": "matrix"
  },
  "status": "success"
}
{
  "error": "missing query parameter",
  "errorType": "bad_data",
  "status": "error"
}
{
  "id": "unauthorized",
  "message": "Unable to authenticate you."
}
{
  "id": "forbidden",
  "message": "You do not have permission to perform this action."
}
{
  "id": "not_found",
  "message": "The resource you requested could not be found."
}
{
  "error": "missing query parameter",
  "errorType": "bad_data",
  "status": "error"
}
{
  "id": "too_many_requests",
  "message": "API rate limit exceeded."
}
{
  "error": "missing query parameter",
  "errorType": "bad_data",
  "status": "error"
}
{
  "error": "missing query parameter",
  "errorType": "bad_data",
  "status": "error"
}
{
  "id": "example_error",
  "message": "some error message"
}

GET List label names

/v2/insights/query/{region}/prom/api/v1/labels
Authorizations: bearer_auth (1 scope)
Http: Bearer
Required scopes: insights: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 label names, send a GET request to /v2/insights/query/{region}/prom/api/v1/labels.

Path Parameters

region string required
Example: nyc3

The datacenter region slug for the query.

Query Parameters

start string optional
Example: 1620683817

Optional start timestamp (inclusive). Accepts a RFC3339 string or a UNIX timestamp.

end string optional
Example: 1620705417

Optional end timestamp (inclusive). Accepts a RFC3339 string or a UNIX timestamp.

match[] array of string optional
Example: ["{__name__=~\".+\"}"]

One or more series selectors. Repeat the parameter for multiple matchers.

Request: /v2/insights/query/{region}/prom/api/v1/labels
curl -X GET \
  -H "Authorization: Bearer $DIGITALOCEAN_TOKEN" \
  "https://api.digitalocean.com/v2/insights/query/nyc3/prom/api/v1/labels"

Responses

200

Label names.
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
data array of string required
Example: ["__name__","job","instance"]
status string, one of: success required
Example: success
400

Prometheus-style query 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
error string required
Example: missing query parameter

Human-readable error message.

errorType string (enum) required
Example: bad_data

Prometheus error category.

status string, one of: error required
Example: error
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.

403

The authenticated principal does not have permission to perform this action on the requested resource.
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.

422

Prometheus-style query 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
error string required
Example: missing query parameter

Human-readable error message.

errorType string (enum) required
Example: bad_data

Prometheus error category.

status string, one of: error required
Example: error
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

Prometheus-style query 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
error string required
Example: missing query parameter

Human-readable error message.

errorType string (enum) required
Example: bad_data

Prometheus error category.

status string, one of: error required
Example: error
503

Prometheus-style query 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
error string required
Example: missing query parameter

Human-readable error message.

errorType string (enum) required
Example: bad_data

Prometheus error category.

status string, one of: error required
Example: error
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
{
  "data": [
    "__name__",
    "job",
    "instance"
  ],
  "status": "success"
}
{
  "error": "missing query parameter",
  "errorType": "bad_data",
  "status": "error"
}
{
  "id": "unauthorized",
  "message": "Unable to authenticate you."
}
{
  "id": "forbidden",
  "message": "You do not have permission to perform this action."
}
{
  "id": "not_found",
  "message": "The resource you requested could not be found."
}
{
  "error": "missing query parameter",
  "errorType": "bad_data",
  "status": "error"
}
{
  "id": "too_many_requests",
  "message": "API rate limit exceeded."
}
{
  "error": "missing query parameter",
  "errorType": "bad_data",
  "status": "error"
}
{
  "error": "missing query parameter",
  "errorType": "bad_data",
  "status": "error"
}
{
  "id": "example_error",
  "message": "some error message"
}

POST List label names

/v2/insights/query/{region}/prom/api/v1/labels
Authorizations: bearer_auth (1 scope)
Http: Bearer
Required scopes: insights: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 label names, send a POST request to /v2/insights/query/{region}/prom/api/v1/labels with application/x-www-form-urlencoded parameters.

Path Parameters

region string required
Example: nyc3

The datacenter region slug for the query.

Request Body: application/x-www-form-urlencoded

end string optional
Example: 1620705417

Optional end timestamp.

match[] array of string optional

Optional series selectors.

start string optional
Example: 1620683817

Optional start timestamp.

Request: /v2/insights/query/{region}/prom/api/v1/labels
Content type application/x-www-form-urlencoded 
{
  "end": "1620705417",
  "match[]": [
    "string"
  ],
  "start": "1620683817"
}
curl -X POST \
  -H "Authorization: Bearer $DIGITALOCEAN_TOKEN" \
  -H "Content-Type: application/x-www-form-urlencoded" \
  --data-urlencode 'match[]={__name__="do.droplets.cpu_time"}' \
  "https://api.digitalocean.com/v2/insights/query/nyc3/prom/api/v1/labels"

Responses

200

Label names.
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
data array of string required
Example: ["__name__","job","instance"]
status string, one of: success required
Example: success
400

Prometheus-style query 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
error string required
Example: missing query parameter

Human-readable error message.

errorType string (enum) required
Example: bad_data

Prometheus error category.

status string, one of: error required
Example: error
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.

403

The authenticated principal does not have permission to perform this action on the requested resource.
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.

422

Prometheus-style query 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
error string required
Example: missing query parameter

Human-readable error message.

errorType string (enum) required
Example: bad_data

Prometheus error category.

status string, one of: error required
Example: error
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

Prometheus-style query 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
error string required
Example: missing query parameter

Human-readable error message.

errorType string (enum) required
Example: bad_data

Prometheus error category.

status string, one of: error required
Example: error
503

Prometheus-style query 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
error string required
Example: missing query parameter

Human-readable error message.

errorType string (enum) required
Example: bad_data

Prometheus error category.

status string, one of: error required
Example: error
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
{
  "data": [
    "__name__",
    "job",
    "instance"
  ],
  "status": "success"
}
{
  "error": "missing query parameter",
  "errorType": "bad_data",
  "status": "error"
}
{
  "id": "unauthorized",
  "message": "Unable to authenticate you."
}
{
  "id": "forbidden",
  "message": "You do not have permission to perform this action."
}
{
  "id": "not_found",
  "message": "The resource you requested could not be found."
}
{
  "error": "missing query parameter",
  "errorType": "bad_data",
  "status": "error"
}
{
  "id": "too_many_requests",
  "message": "API rate limit exceeded."
}
{
  "error": "missing query parameter",
  "errorType": "bad_data",
  "status": "error"
}
{
  "error": "missing query parameter",
  "errorType": "bad_data",
  "status": "error"
}
{
  "id": "example_error",
  "message": "some error message"
}

GET List values for a label

/v2/insights/query/{region}/prom/api/v1/label/{name}/values
Authorizations: bearer_auth (1 scope)
Http: Bearer
Required scopes: insights: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 values for a label name, send a GET request to /v2/insights/query/{region}/prom/api/v1/label/{name}/values.

Path Parameters

region string required
Example: nyc3

The datacenter region slug for the query.

name string required
Example: __name__

The label name whose values should be listed.

Query Parameters

start string optional
Example: 1620683817

Optional start timestamp (inclusive). Accepts a RFC3339 string or a UNIX timestamp.

end string optional
Example: 1620705417

Optional end timestamp (inclusive). Accepts a RFC3339 string or a UNIX timestamp.

match[] array of string optional
Example: ["{__name__=~\".+\"}"]

One or more series selectors. Repeat the parameter for multiple matchers.

Request: /v2/insights/query/{region}/prom/api/v1/label/{name}/values
curl -X GET \
  -H "Authorization: Bearer $DIGITALOCEAN_TOKEN" \
  "https://api.digitalocean.com/v2/insights/query/nyc3/prom/api/v1/label/__name__/values"

Responses

200

Label values.
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
data array of string required
Example: ["__name__","job","instance"]
status string, one of: success required
Example: success
400

Prometheus-style query 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
error string required
Example: missing query parameter

Human-readable error message.

errorType string (enum) required
Example: bad_data

Prometheus error category.

status string, one of: error required
Example: error
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.

403

The authenticated principal does not have permission to perform this action on the requested resource.
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.

422

Prometheus-style query 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
error string required
Example: missing query parameter

Human-readable error message.

errorType string (enum) required
Example: bad_data

Prometheus error category.

status string, one of: error required
Example: error
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

Prometheus-style query 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
error string required
Example: missing query parameter

Human-readable error message.

errorType string (enum) required
Example: bad_data

Prometheus error category.

status string, one of: error required
Example: error
503

Prometheus-style query 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
error string required
Example: missing query parameter

Human-readable error message.

errorType string (enum) required
Example: bad_data

Prometheus error category.

status string, one of: error required
Example: error
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
{
  "data": [
    "do_droplets_cpu_time",
    "do_droplets_memory_free"
  ],
  "status": "success"
}
{
  "error": "missing query parameter",
  "errorType": "bad_data",
  "status": "error"
}
{
  "id": "unauthorized",
  "message": "Unable to authenticate you."
}
{
  "id": "forbidden",
  "message": "You do not have permission to perform this action."
}
{
  "id": "not_found",
  "message": "The resource you requested could not be found."
}
{
  "error": "missing query parameter",
  "errorType": "bad_data",
  "status": "error"
}
{
  "id": "too_many_requests",
  "message": "API rate limit exceeded."
}
{
  "error": "missing query parameter",
  "errorType": "bad_data",
  "status": "error"
}
{
  "error": "missing query parameter",
  "errorType": "bad_data",
  "status": "error"
}
{
  "id": "example_error",
  "message": "some error message"
}

GET Find series by label selectors

/v2/insights/query/{region}/prom/api/v1/series
Authorizations: bearer_auth (1 scope)
Http: Bearer
Required scopes: insights: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 find series matching one or more selectors, send a GET request to /v2/insights/query/{region}/prom/api/v1/series.

Path Parameters

region string required
Example: nyc3

The datacenter region slug for the query.

Query Parameters

match[] array of string required
Example: ["{__name__=\"do.droplets.cpu_time\"}"]

One or more series selectors. At least one matcher is required. Repeat the parameter for multiple matchers.

start string optional
Example: 1620683817

Optional start timestamp (inclusive). Accepts a RFC3339 string or a UNIX timestamp.

end string optional
Example: 1620705417

Optional end timestamp (inclusive). Accepts a RFC3339 string or a UNIX timestamp.

Request: /v2/insights/query/{region}/prom/api/v1/series
curl -X GET \
  -H "Authorization: Bearer $DIGITALOCEAN_TOKEN" \
  --get "https://api.digitalocean.com/v2/insights/query/nyc3/prom/api/v1/series" \
  --data-urlencode 'match[]={__name__="do.droplets.cpu_time"}'

Responses

200

Matching series label sets.
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
data array of object required
status string, one of: success required
Example: success
400

Prometheus-style query 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
error string required
Example: missing query parameter

Human-readable error message.

errorType string (enum) required
Example: bad_data

Prometheus error category.

status string, one of: error required
Example: error
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.

403

The authenticated principal does not have permission to perform this action on the requested resource.
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.

422

Prometheus-style query 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
error string required
Example: missing query parameter

Human-readable error message.

errorType string (enum) required
Example: bad_data

Prometheus error category.

status string, one of: error required
Example: error
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

Prometheus-style query 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
error string required
Example: missing query parameter

Human-readable error message.

errorType string (enum) required
Example: bad_data

Prometheus error category.

status string, one of: error required
Example: error
503

Prometheus-style query 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
error string required
Example: missing query parameter

Human-readable error message.

errorType string (enum) required
Example: bad_data

Prometheus error category.

status string, one of: error required
Example: error
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
{
  "data": [
    {
      "__name__": "do_droplets_cpu_time"
    }
  ],
  "status": "success"
}
{
  "error": "missing query parameter",
  "errorType": "bad_data",
  "status": "error"
}
{
  "id": "unauthorized",
  "message": "Unable to authenticate you."
}
{
  "id": "forbidden",
  "message": "You do not have permission to perform this action."
}
{
  "id": "not_found",
  "message": "The resource you requested could not be found."
}
{
  "error": "missing query parameter",
  "errorType": "bad_data",
  "status": "error"
}
{
  "id": "too_many_requests",
  "message": "API rate limit exceeded."
}
{
  "error": "missing query parameter",
  "errorType": "bad_data",
  "status": "error"
}
{
  "error": "missing query parameter",
  "errorType": "bad_data",
  "status": "error"
}
{
  "id": "example_error",
  "message": "some error message"
}

POST Find series by label selectors

/v2/insights/query/{region}/prom/api/v1/series
Authorizations: bearer_auth (1 scope)
Http: Bearer
Required scopes: insights: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 find series matching one or more selectors, send a POST request to /v2/insights/query/{region}/prom/api/v1/series with application/x-www-form-urlencoded parameters.

Path Parameters

region string required
Example: nyc3

The datacenter region slug for the query.

Request Body: application/x-www-form-urlencoded

end string optional
Example: 1620705417

Optional end timestamp.

match[] array of string required

One or more series selectors.

start string optional
Example: 1620683817

Optional start timestamp.

Request: /v2/insights/query/{region}/prom/api/v1/series
Content type application/x-www-form-urlencoded 
{
  "end": "1620705417",
  "match[]": [
    "string"
  ],
  "start": "1620683817"
}
curl -X POST \
  -H "Authorization: Bearer $DIGITALOCEAN_TOKEN" \
  -H "Content-Type: application/x-www-form-urlencoded" \
  --data-urlencode 'match[]={__name__="do.droplets.cpu_time"}' \
  "https://api.digitalocean.com/v2/insights/query/nyc3/prom/api/v1/series"

Responses

200

Matching series label sets.
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
data array of object required
status string, one of: success required
Example: success
400

Prometheus-style query 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
error string required
Example: missing query parameter

Human-readable error message.

errorType string (enum) required
Example: bad_data

Prometheus error category.

status string, one of: error required
Example: error
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.

403

The authenticated principal does not have permission to perform this action on the requested resource.
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.

422

Prometheus-style query 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
error string required
Example: missing query parameter

Human-readable error message.

errorType string (enum) required
Example: bad_data

Prometheus error category.

status string, one of: error required
Example: error
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

Prometheus-style query 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
error string required
Example: missing query parameter

Human-readable error message.

errorType string (enum) required
Example: bad_data

Prometheus error category.

status string, one of: error required
Example: error
503

Prometheus-style query 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
error string required
Example: missing query parameter

Human-readable error message.

errorType string (enum) required
Example: bad_data

Prometheus error category.

status string, one of: error required
Example: error
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
{
  "data": [
    {
      "__name__": "do_droplets_cpu_time"
    }
  ],
  "status": "success"
}
{
  "error": "missing query parameter",
  "errorType": "bad_data",
  "status": "error"
}
{
  "id": "unauthorized",
  "message": "Unable to authenticate you."
}
{
  "id": "forbidden",
  "message": "You do not have permission to perform this action."
}
{
  "id": "not_found",
  "message": "The resource you requested could not be found."
}
{
  "error": "missing query parameter",
  "errorType": "bad_data",
  "status": "error"
}
{
  "id": "too_many_requests",
  "message": "API rate limit exceeded."
}
{
  "error": "missing query parameter",
  "errorType": "bad_data",
  "status": "error"
}
{
  "error": "missing query parameter",
  "errorType": "bad_data",
  "status": "error"
}
{
  "id": "example_error",
  "message": "some error message"
}

POST Search logs

/v2/insights/query/{region}/logs/search
Authorizations: bearer_auth (1 scope)
Http: Bearer
Required scopes: insights: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 search log records in a region, send a POST request to /v2/insights/query/{region}/logs/search with a JSON body describing the time range, optional filter, ordering, and pagination. The time range must not exceed 7 days. pagination.limit defaults to 100 and is clamped to 1000. Cursor pagination requires ordering by timestamp alone; other sort orders return has_more: false and cannot be paged.

Path Parameters

region string required
Example: nyc3

The datacenter region slug for the query.

Request Body: application/json

filter object optional

A boolean filter tree for logs queries. Exactly one node is set per message.

Show child properties
and object optional
Show child properties
expressions array of object required
condition object optional

A single field comparison in a logs filter expression.

Show child properties
field object required

A reference to a logical field for filters, ordering, grouping, or facets.

Show child properties
name string required
Example: service.name

The field name. Intrinsic columns include timestamp, severity_text, severity_number, body, trace_id, span_id, and trace_flags. The dotted shorthands service.name, resource.type, and resource.urn are also supported. Arbitrary resource or log attributes can be accessed with ResourceAttributes['key'] or LogAttributes['key'].

scope string, one of: FIELD_SCOPE_RESOURCE, FIELD_SCOPE_ATTRIBUTES optional
Example: FIELD_SCOPE_RESOURCE

The attribute scope to resolve the field against. Omit to let the server apply its default mapping for the field name.

operator string (enum) required
Example: FILTER_OPERATOR_EQ

The comparison operator.

value object optional

A typed literal or list value for a filter condition. Exactly one kind is set per message.

Show child properties
bool_value boolean optional
Example: true
number_array_value object optional
Additional nested properties not shown. Refer to the full API spec for details.
number_value number optional
Example: 42
string_array_value object optional
Additional nested properties not shown. Refer to the full API spec for details.
string_value string optional
Example: droplet-123
not object optional

A boolean filter tree for logs queries. Exactly one node is set per message.

or object optional
Show child properties
expressions array of object required
text_search object optional

A substring search across the log body, service name, and resource URN.

Show child properties
query string required
Example: error

The search string.

order_by array of object optional

Sort clauses applied to the result set.

Show child properties
direction string, one of: SORT_DIRECTION_ASC, SORT_DIRECTION_DESC optional
Example: SORT_DIRECTION_DESC

The sort direction. Omit to use the server default.

field object required

A reference to a logical field for filters, ordering, grouping, or facets.

Show child properties
name string required
Example: service.name

The field name. Intrinsic columns include timestamp, severity_text, severity_number, body, trace_id, span_id, and trace_flags. The dotted shorthands service.name, resource.type, and resource.urn are also supported. Arbitrary resource or log attributes can be accessed with ResourceAttributes['key'] or LogAttributes['key'].

scope string, one of: FIELD_SCOPE_RESOURCE, FIELD_SCOPE_ATTRIBUTES optional
Example: FIELD_SCOPE_RESOURCE

The attribute scope to resolve the field against. Omit to let the server apply its default mapping for the field name.

pagination object optional

Opaque keyset pagination request. Cursors are only valid when ordering by timestamp alone.

Show child properties
cursor string optional
Example: eyJ0cyI6MTc1NjY4NDgwMDAwMDAwMDAwfQ

Opaque cursor from a previous response.

limit integer (int32) optional
Example: 100

Maximum number of results to return. Defaults to 100 and is clamped to 1000.

time_range object required

An inclusive query time window.

Show child properties
from object required

A single point in time. Exactly one value form is set per message.

Show child properties
absolute string (date-time) optional
Example: 2026-09-01T00:00:00Z

An absolute timestamp. Accepts RFC3339/RFC3339Nano strings or Unix seconds/nanoseconds as decimal strings.

relative string optional
Example: 1h

A relative time. Use now for the current time, a bare duration such as 1h or 7d to look back from now, or an offset such as now-1h or now+30m. Supported units are s, m, h, d, and w.

unix_nano string (int64) optional
Example: 1756684800000000000

A Unix nanosecond timestamp, encoded as a string to preserve 64-bit precision.

to object required

A single point in time. Exactly one value form is set per message.

Show child properties
absolute string (date-time) optional
Example: 2026-09-01T00:00:00Z

An absolute timestamp. Accepts RFC3339/RFC3339Nano strings or Unix seconds/nanoseconds as decimal strings.

relative string optional
Example: 1h

A relative time. Use now for the current time, a bare duration such as 1h or 7d to look back from now, or an offset such as now-1h or now+30m. Supported units are s, m, h, d, and w.

unix_nano string (int64) optional
Example: 1756684800000000000

A Unix nanosecond timestamp, encoded as a string to preserve 64-bit precision.

Request: /v2/insights/query/{region}/logs/search
Content type application/json 
{
  "filter": {
    "and": {
      "expressions": []
    },
    "condition": {
      "operator": "FILTER_OPERATOR_EQ"
    },
    "or": {
      "expressions": []
    },
    "text_search": {
      "query": "error"
    }
  },
  "order_by": [
    {
      "direction": "SORT_DIRECTION_DESC"
    }
  ],
  "pagination": {
    "cursor": "eyJ0cyI6MTc1NjY4NDgwMDAwMDAwMDAwfQ",
    "limit": 100
  },
  "time_range": {
    "from": {
      "absolute": "2026-09-01T00:00:00Z",
      "relative": "1h",
      "unix_nano": "1756684800000000000"
    },
    "to": {
      "absolute": "2026-09-01T00:00:00Z",
      "relative": "1h",
      "unix_nano": "1756684800000000000"
    }
  }
}
curl -X POST \
  -H "Authorization: Bearer $DIGITALOCEAN_TOKEN" \
  -H "Content-Type: application/json" \
  -d '{
    "time_range": {
      "from": {"absolute": "2026-09-30T00:00:00Z"},
      "to": {"absolute": "2026-09-30T01:00:00Z"}
    },
    "filter": {
      "condition": {
        "field": {"name": "severity_text"},
        "operator": "FILTER_OPERATOR_EQ",
        "value": {"string_value": "Error"}
      }
    },
    "order_by": [
      {"field": {"name": "timestamp"}, "direction": "SORT_DIRECTION_DESC"}
    ],
    "pagination": {"limit": 100}
  }' \
  "https://api.digitalocean.com/v2/insights/query/nyc3/logs/search"

Responses

200

Logs search result.
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
data array of object optional

Matching log records. Omitted when no records match.

Show child properties
attributes object optional
Example: {"http.method":"GET","http.status_code":"504"}

Log attributes.

body string optional
Example: Connection timeout

The log message body. Omitted when empty.

resource object optional
Example: {"do.component":"droplet","do.droplet.id":"12345678"}

Resource attributes associated with the log.

service_name string optional
Example: api-gateway

The service name that emitted the log.

severity_number integer (int32) optional
Example: 17

The numeric severity level.

severity_text string optional
Example: Error

The textual severity level.

span_id string optional
Example: def456

The span ID if present.

timestamp string (date-time) required
Example: 2026-09-01T00:00:00Z

The log record timestamp.

trace_id string optional
Example: abc123

The trace ID if present.

pagination object optional

Pagination response.

Show child properties
has_more boolean optional
Example: true

Whether more results are available.

next_cursor string optional
Example: eyJ0cyI6MTc1NjY4NDgwMDAwMDAwMDAwfQ

Opaque cursor to fetch the next page.

400

There was an error parsing the request body.
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.

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.

403

The authenticated principal does not have permission to perform this action on the requested resource.
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
{
  "data": [
    {
      "attributes": {
        "http.method": "GET",
        "http.status_code": "504"
      },
      "body": "Connection timeout",
      "resource": {
        "do.component": "droplet",
        "do.droplet.id": "12345678"
      },
      "service_name": "api-gateway",
      "severity_number": 17,
      "severity_text": "Error",
      "span_id": "def456",
      "timestamp": "2026-09-01T00:00:00Z",
      "trace_id": "abc123"
    }
  ],
  "pagination": {
    "has_more": true,
    "next_cursor": "eyJ0cyI6MTc1NjY4NDgwMDAwMDAwMDAwfQ"
  }
}
{
  "id": "bad_request",
  "message": "error parsing request body",
  "request_id": "4851a473-1621-42ea-b2f9-5071c0ea8414"
}
{
  "id": "unauthorized",
  "message": "Unable to authenticate you."
}
{
  "id": "forbidden",
  "message": "You do not have permission to perform this action."
}
{
  "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"
}

POST Search traces

/v2/insights/query/{region}/traces/search
Authorizations: bearer_auth (1 scope)
Http: Bearer
Required scopes: insights: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 search traces in a region, send a POST request to /v2/insights/query/{region}/traces/search with a JSON body describing the time range, optional filter, ordering, and pagination. Each result is one trace, aggregated from all of its spans in the time range. A trace is included when at least one of its spans matches filter. The time range must not exceed 7 days (168h). pagination.limit defaults to 100 (also used when limit is 0) and must be between 0 and 1000. Results are ordered by started descending unless order_by is set. JSON field names use snake_case (time_range, order_by, has_more, trace_id). Unknown request properties, invalid filters, and out-of-range values are rejected with 400. Each request searches a single region; there is no multi-region search. Supported regions are ams2, ams3, atl1, blr1, fra1, lon1, mem1, nyc1, nyc2, nyc3, ric1, sfo1, sfo2, sfo3, sgp1, syd1, and tor1. Requests time out after 60 seconds. Errors produced by the traces service (400) have a text/plain body containing a short message. Authentication and authorization errors (401, 403), rate limiting (429), and routing errors (for example, 404 for an unknown region) come from the API gateway and use the standard JSON error object with id and message. 403 is also returned for accounts that are in a trial or not in good standing. If the regional traces backend cannot be reached, the response is 502 with a text/plain body.

Path Parameters

region string required
Example: nyc3

The datacenter region slug for the query.

Request Body: application/json

filter string optional

A boolean filter tree for traces queries. Exactly one node is set per message. Trees may be nested at most 16 levels deep and contain at most 256 nodes in total.

order_by array of object optional

Sort clauses applied in order. Defaults to started descending.

Show child properties
direction string, one of: asc, desc optional
Example: desc

The sort direction, matched case-insensitively. Omit to use the server default.

field object required

A reference to a span field, used in filters and order_by.

Show child properties
name string required
Example: service.name

The field name. Without scope, these names (case-insensitive) resolve to built-in span columns: trace_id, span_id, parent_span_id, start_time, end_time, duration_ns, name (span.name), kind (span.kind), status_code (status.code, status_code), status_message, and service_name (service.name). Any other name is looked up as a span attribute, falling back to a resource attribute. With scope set, name is always treated as an attribute key. Attribute keys may contain only letters, digits, and ., _, -, /, :, @.

In traces order_by, name must be a trace-level sort field instead; see the order_by field description.

scope string (enum) optional
Example: FIELD_SCOPE_RESOURCE

Restricts the lookup to one attribute map and is matched case-insensitively. FIELD_SCOPE_RESOURCE reads resource attributes and accepts resource or resource.attributes as aliases. FIELD_SCOPE_ATTRIBUTES reads span attributes and accepts attribute, attributes, or span.attributes as aliases. Omit to use the built-in column mapping described for name. Ignored in traces order_by.

pagination object optional

Limits the size of a traces search result set. There is no cursor; use pagination.has_more in the response to tell whether more traces matched, and narrow the time range or filter to see them.

Show child properties
limit integer (int32) optional
Example: 50

Maximum number of traces to return. Omitted or 0 uses the default of 100. Negative values or values above 1000 return 400; they are not clamped.

time_range object required

An inclusive query time window. Both bounds are required, from must not be after to, and the window must not exceed 7 days (168h).

Show child properties
from object required

A single point in time. Set absolute or relative; if both are set, absolute is used.

Show child properties
absolute string optional
Example: 2026-10-09T00:00:00Z

An absolute timestamp, either RFC3339 (with optional fractional seconds) or a Unix epoch integer as a decimal string. Epoch precision is inferred from magnitude: seconds, milliseconds, microseconds, or nanoseconds.

relative string optional
Example: 15m

A time relative to now. Use now for the current time, a bare duration such as 15m or 24h to look back from now, or an offset such as now-2h or now+30m. Supported units are s, m, h, d, and w; decimal amounts such as 1.5h are allowed.

to object required

A single point in time. Set absolute or relative; if both are set, absolute is used.

Show child properties
absolute string optional
Example: 2026-10-09T00:00:00Z

An absolute timestamp, either RFC3339 (with optional fractional seconds) or a Unix epoch integer as a decimal string. Epoch precision is inferred from magnitude: seconds, milliseconds, microseconds, or nanoseconds.

relative string optional
Example: 15m

A time relative to now. Use now for the current time, a bare duration such as 15m or 24h to look back from now, or an offset such as now-2h or now+30m. Supported units are s, m, h, d, and w; decimal amounts such as 1.5h are allowed.

Request: /v2/insights/query/{region}/traces/search
Content type application/json
Example 
{
  "filter": {
    "and": {
      "expressions": [
        {
          "condition": {
            "field": {
              "name": "status_code"
            },
            "operator": "FILTER_OPERATOR_EQ",
            "value": {
              "string_value": "Error"
            }
          }
        },
        {
          "condition": {
            "field": {
              "name": "host.name",
              "scope": "FIELD_SCOPE_RESOURCE"
            },
            "operator": "FILTER_OPERATOR_IN",
            "value": {
              "string_array_value": {
                "values": [
                  "web-01",
                  "web-02"
                ]
              }
            }
          }
        }
      ]
    }
  },
  "time_range": {
    "from": {
      "absolute": "2026-10-09T00:00:00Z"
    },
    "to": {
      "absolute": "2026-10-09T06:00:00Z"
    }
  }
}
curl -X POST \
  -H "Authorization: Bearer $DIGITALOCEAN_TOKEN" \
  -H "Content-Type: application/json" \
  -d '{
    "time_range": {
      "from": {"relative": "24h"},
      "to": {"relative": "now"}
    },
    "filter": {
      "and": {
        "expressions": [
          {"condition": {"field": {"name": "service.name"}, "operator": "FILTER_OPERATOR_EQ", "value": {"string_value": "checkout-api"}}},
          {"text_search": {"query": "timeout"}}
        ]
      }
    },
    "order_by": [{"field": {"name": "duration_ns"}, "direction": "desc"}],
    "pagination": {"limit": 50}
  }' \
  "https://api.digitalocean.com/v2/insights/query/nyc3/traces/search"

Responses

200

Traces search result.
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
data array of object required

Matching traces. Empty when no traces match.

Show child properties
duration_ns integer (int64) optional
Example: 10000000

Wall-clock duration of the trace in nanoseconds.

error_count integer (int32) optional
Example: 1

The number of spans in the trace with an Error status code. Omitted when zero.

service_name string optional
Example: checkout-api

The service that emitted the root span. Omitted when the root span has no service.name resource attribute.

span_count integer (int32) optional
Example: 1

The number of spans in the trace.

span_names array of string optional
Example: ["checkout-api-root"]

The distinct span names present in the trace.

started string (date-time) optional
Example: 2026-10-09T09:21:39.99Z

The start time of the earliest span in the trace, in RFC 3339 format.

status string, one of: Ok, Error optional
Example: Ok

The rolled-up status of the trace. Error if any span has an Error status code, otherwise Ok.

trace_id string required
Example: bef35030c4024f42fb88041fea062e97

The trace identifier.

pagination object required

Pagination response.

Show child properties
has_more boolean required
Example: false

Whether more results matched the query than were returned.

400

The request was rejected by the traces service, for example because the body is malformed, a field is out of range, or the time range is invalid. The body is a short plain-text message.
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.

403

The authenticated principal does not have permission to perform this action on the requested resource.
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 trace or region was not found. When the traces service finds no matching trace, the body is the plain-text message trace not found. When the region is unknown or does not serve traces, the API gateway returns a JSON error object.
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.

502

The regional traces backend could not be reached. The body is a short plain-text message.
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.

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
{
  "data": [
    {
      "duration_ns": 10000000,
      "service_name": "checkout-api",
      "span_count": 1,
      "span_names": [
        "checkout-api-root"
      ],
      "started": "2026-10-09T09:21:39.99Z",
      "status": "Ok",
      "trace_id": "bef35030c4024f42fb88041fea062e97"
    }
  ],
  "pagination": {
    "has_more": false
  }
}
Example 
"time_range.from must be before or equal to time_range.to"
{
  "id": "unauthorized",
  "message": "Unable to authenticate you."
}
{
  "id": "forbidden",
  "message": "You do not have permission to perform this action."
}
{
  "id": "not_found",
  "message": "Your request could not be routed."
}
{
  "id": "too_many_requests",
  "message": "API rate limit exceeded."
}
{
  "id": "server_error",
  "message": "Unexpected server-side error"
}
Bad Gateway
{
  "id": "example_error",
  "message": "some error message"
}

GET Retrieve an existing trace

/v2/insights/query/{region}/traces/{trace_id}
Authorizations: bearer_auth (1 scope)
Http: Bearer
Required scopes: insights: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 retrieve a single trace and all of its spans, send a GET request to /v2/insights/query/{region}/traces/{trace_id}. Only spans that started within the lookup window are returned. The window defaults to the last 7 days and can be narrowed with the from and to query parameters; it must not exceed 7 days, and from must not be after to. Spans are returned ordered by start time. At most 10,000 spans are returned; truncated is true when the trace has more. A trace ID with no spans in the window returns 404, as do malformed or uppercase trace IDs. A trace is only resolvable in the region that ingested it; querying another region also returns 404. Supported regions are ams2, ams3, atl1, blr1, fra1, lon1, mem1, nyc1, nyc2, nyc3, ric1, sfo1, sfo2, sfo3, sgp1, syd1, and tor1. Requests time out after 60 seconds. Errors produced by the traces service (400, and 404 when no trace is found) have a text/plain body containing a short message. Authentication and authorization errors (401, 403), rate limiting (429), and routing errors (for example, 404 for an unknown region) come from the API gateway and use the standard JSON error object with id and message. 403 is also returned for accounts that are in a trial or not in good standing. If the regional traces backend cannot be reached, the response is 502 with a text/plain body. JSON field names use snake_case (trace_id, span_id, start_time, end_time, duration_ns, service_name, status_code, parent_span_id).

Path Parameters

region string required
Example: nyc3

The datacenter region slug for the query.

trace_id string required
Example: 7b0b4e56abab38362b24e5498eb9ec64

The OpenTelemetry trace ID to retrieve, as 32 lowercase hexadecimal characters. IDs are matched exactly; an ID with no spans in the lookup window returns 404. Malformed or uppercase IDs are not rejected with 400; they also return 404.

Query Parameters

from string optional
Example: 24h

Start of the trace lookup window. Accepts a relative time (now, a bare duration such as 24h to look back from now, or now-2h) or an absolute time (RFC3339, or a Unix epoch integer in seconds, milliseconds, microseconds, or nanoseconds). Defaults to 7 days before now.

to string optional
Example: now

End of the trace lookup window, in the same formats as from. Defaults to now.

Request: /v2/insights/query/{region}/traces/{trace_id}
curl -X GET \
  -H "Authorization: Bearer $DIGITALOCEAN_TOKEN" \
  "https://api.digitalocean.com/v2/insights/query/nyc3/traces/7b0b4e56abab38362b24e5498eb9ec64?from=24h&to=now"

Responses

200

The trace and its spans.
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
spans array of object optional

Every span in the trace, ordered by start time.

Show child properties
attributes object optional
Example: {"http.method":"GET"}

Span attributes. Omitted when empty.

duration_ns integer (int64) optional
Example: 200000000

Span duration in nanoseconds.

end_time string (date-time) optional
Example: 2026-10-09T06:44:39Z

The span end time.

kind string optional
Example: Server

The OpenTelemetry span kind as a string, for example Server, Client, or Internal.

name string optional
Example: GET /checkout

The span name, typically the operation being performed.

parent_span_id string optional
Example: a2fb4a1d1a96d312

The parent span identifier. Omitted for the root span.

resource object optional
Example: {"service.name":"checkout-api"}

Resource attributes associated with the span.

service_name string optional
Example: checkout-api

The service that emitted the span. Omitted when the span has no service.name resource attribute.

span_id string required
Example: e7867486e45cda47

The span identifier.

start_time string (date-time) optional
Example: 2026-10-09T06:44:37Z

The span start time.

status_code string optional
Example: Error

The OpenTelemetry span status code as a string: Unset, Ok, or Error.

status_message string optional
Example: upstream timeout

The status description. Omitted when empty.

trace_id string required
Example: 7b0b4e56abab38362b24e5498eb9ec64

The trace this span belongs to.

trace_id string optional
Example: 7b0b4e56abab38362b24e5498eb9ec64

The trace identifier.

truncated boolean optional
Example: false

True when the trace has more spans than were returned in this response. Omitted when false.

400

The request was rejected by the traces service, for example because the body is malformed, a field is out of range, or the time range is invalid. The body is a short plain-text message.
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.

403

The authenticated principal does not have permission to perform this action on the requested resource.
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 trace or region was not found. When the traces service finds no matching trace, the body is the plain-text message trace not found. When the region is unknown or does not serve traces, the API gateway returns a JSON error object.
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.

502

The regional traces backend could not be reached. The body is a short plain-text message.
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.

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
{
  "spans": [
    {
      "attributes": {
        "http.method": "GET"
      },
      "duration_ns": 200000000,
      "end_time": "2026-10-09T06:44:39Z",
      "kind": "Server",
      "name": "GET /checkout",
      "parent_span_id": "a2fb4a1d1a96d312",
      "resource": {
        "service.name": "checkout-api"
      },
      "service_name": "checkout-api",
      "span_id": "e7867486e45cda47",
      "start_time": "2026-10-09T06:44:37Z",
      "status_code": "Error",
      "status_message": "upstream timeout",
      "trace_id": "7b0b4e56abab38362b24e5498eb9ec64"
    }
  ],
  "trace_id": "7b0b4e56abab38362b24e5498eb9ec64",
  "truncated": false
}
Example 
"time_range.from must be before or equal to time_range.to"
{
  "id": "unauthorized",
  "message": "Unable to authenticate you."
}
{
  "id": "forbidden",
  "message": "You do not have permission to perform this action."
}
{
  "id": "not_found",
  "message": "Your request could not be routed."
}
{
  "id": "too_many_requests",
  "message": "API rate limit exceeded."
}
{
  "id": "server_error",
  "message": "Unexpected server-side error"
}
Bad Gateway
{
  "id": "example_error",
  "message": "some error message"
}

POST Search spans

/v2/insights/query/{region}/spans/search
Authorizations: bearer_auth (1 scope)
Http: Bearer
Required scopes: insights: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 search spans in a region, send a POST request to /v2/insights/query/{region}/spans/search with a JSON body describing the time range, optional filter, ordering, and pagination. The time range must not exceed 7 days. pagination.limit defaults to 100 and must be between 1 and 1000. Results are ordered by start_time descending by default. Cursor-based pagination is not yet supported; pagination.has_more indicates whether additional spans matched beyond the returned page.

Path Parameters

region string required
Example: nyc3

The datacenter region slug for the query.

Request Body: application/json

filter string optional

A boolean filter tree for spans queries. Exactly one node is set per message. Trees may be nested at most 16 levels deep and contain at most 256 nodes in total.

order_by array of object optional

Sort clauses applied to the result set. Defaults to start_time descending when omitted.

Show child properties
direction string, one of: asc, desc optional
Example: desc

The sort direction, matched case-insensitively. Omit to use the server default.

field object required

A reference to a searchable span field.

Show child properties
name string required
Example: service.name

The field name. Well-known span fields include trace_id, span_id, parent_span_id, start_time, end_time, duration_ns, name, service_name, kind, status_code, and status_message. Any other value is treated as a span or resource attribute key.

scope string (enum) optional
Example: FIELD_SCOPE_ATTRIBUTES

Optional attribute scope, matched case-insensitively. Use FIELD_SCOPE_RESOURCE to match a resource attribute or FIELD_SCOPE_ATTRIBUTES to match a span attribute. The aliases resource and resource.attributes are accepted for resource attributes; attribute, attributes, and span.attributes are accepted for span attributes. Omit for well-known fields or to search both attribute maps.

pagination object optional

Limits the number of spans returned.

Show child properties
limit integer (int32) optional
Example: 100

Maximum number of spans to return. Defaults to 100 and must be between 1 and 1000.

time_range object required

An inclusive query time window. The window must not exceed 7 days.

Show child properties
from object required

A single time bound. Exactly one of relative or absolute is set.

Show child properties
absolute string optional
Example: 2026-09-30T00:00:00Z

An absolute timestamp. Accepts an RFC3339/RFC3339Nano string or a Unix timestamp (seconds, milliseconds, microseconds, or nanoseconds) encoded as a decimal string.

relative string optional
Example: 1h

A relative time. Use now for the current time, a bare duration such as 1h or 7d to look back from now, or an offset such as now-15m or now+30m. Supported units are s, m, h, d, and w.

to object required

A single time bound. Exactly one of relative or absolute is set.

Show child properties
absolute string optional
Example: 2026-09-30T00:00:00Z

An absolute timestamp. Accepts an RFC3339/RFC3339Nano string or a Unix timestamp (seconds, milliseconds, microseconds, or nanoseconds) encoded as a decimal string.

relative string optional
Example: 1h

A relative time. Use now for the current time, a bare duration such as 1h or 7d to look back from now, or an offset such as now-15m or now+30m. Supported units are s, m, h, d, and w.

Request: /v2/insights/query/{region}/spans/search
Content type application/json 
{
  "order_by": [
    {
      "direction": "desc"
    }
  ],
  "pagination": {
    "limit": 100
  },
  "time_range": {
    "from": {
      "absolute": "2026-09-30T00:00:00Z",
      "relative": "1h"
    },
    "to": {
      "absolute": "2026-09-30T00:00:00Z",
      "relative": "1h"
    }
  }
}
curl -X POST \
  -H "Authorization: Bearer $DIGITALOCEAN_TOKEN" \
  -H "Content-Type: application/json" \
  -d '{
    "time_range": {
      "from": {"relative": "1h"},
      "to": {"relative": "now"}
    },
    "filter": {
      "and": {
        "expressions": [
          {"condition": {
            "field": {"name": "service.name"},
            "operator": "FILTER_OPERATOR_EQ",
            "value": {"string_value": "api-gateway"}
          }},
          {"condition": {
            "field": {"name": "status_code"},
            "operator": "FILTER_OPERATOR_EQ",
            "value": {"string_value": "Error"}
          }}
        ]
      }
    },
    "order_by": [
      {"field": {"name": "start_time"}, "direction": "desc"}
    ],
    "pagination": {"limit": 100}
  }' \
  "https://api.digitalocean.com/v2/insights/query/nyc3/spans/search"

Responses

200

Spans search result.
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
data array of object optional

Matching spans. Empty when no spans match.

Show child properties
attributes object optional
Example: {"http.method":"GET","http.status_code":"200"}

Span attributes.

duration_ns integer (int64) optional
Example: 1000000

The span duration in nanoseconds.

end_time string (date-time) optional
Example: 2026-09-30T00:00:01Z

The span end time.

kind string optional
Example: Server

The span kind.

name string optional
Example: GET /v2/droplets

The span name.

parent_span_id string optional
Example: 00f067aa0ba902b6

The parent span identifier. Omitted for root spans.

region string optional
Example: nyc3

The datacenter region slug the span was queried from.

resource object optional
Example: {"service.name":"api-gateway","service.version":"1.4.2"}

Resource attributes associated with the span.

service_name string optional
Example: api-gateway

The name of the service that emitted the span.

span_id string optional
Example: 00f067aa0ba902b7

The span identifier.

start_time string (date-time) optional
Example: 2026-09-30T00:00:00Z

The span start time.

status_code string optional
Example: Ok

The span status code.

status_message string optional
Example: connection reset by peer

The span status message. Omitted when empty.

trace_id string optional
Example: 4bf92f3577b34da6a3ce929d0e0e4736

The trace identifier the span belongs to.

pagination object optional

Pagination metadata for a spans search response.

Show child properties
has_more boolean optional
Example: true

Whether more spans matched than were returned in this page. Cursor-based continuation is not yet supported.

400

There was an error parsing the request body.
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.

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.

403

The authenticated principal does not have permission to perform this action on the requested resource.
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
{
  "data": [
    {
      "attributes": {
        "http.method": "GET",
        "http.status_code": "200"
      },
      "duration_ns": 1000000,
      "end_time": "2026-09-30T00:00:01Z",
      "kind": "Server",
      "name": "GET /v2/droplets",
      "parent_span_id": "00f067aa0ba902b6",
      "region": "nyc3",
      "resource": {
        "service.name": "api-gateway",
        "service.version": "1.4.2"
      },
      "service_name": "api-gateway",
      "span_id": "00f067aa0ba902b7",
      "start_time": "2026-09-30T00:00:00Z",
      "status_code": "Ok",
      "status_message": "connection reset by peer",
      "trace_id": "4bf92f3577b34da6a3ce929d0e0e4736"
    }
  ],
  "pagination": {
    "has_more": true
  }
}
{
  "id": "bad_request",
  "message": "error parsing request body",
  "request_id": "4851a473-1621-42ea-b2f9-5071c0ea8414"
}
{
  "id": "unauthorized",
  "message": "Unable to authenticate you."
}
{
  "id": "forbidden",
  "message": "You do not have permission to perform this action."
}
{
  "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 Resource Signal Enablement

/v2/insights/resources
Authorizations: bearer_auth (1 scope)
Http: Bearer
Required scopes: insights: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 resources in your account that have telemetry signal enablement recorded, along with the current state of their metrics, logs, and traces signals, send a GET request to /v2/insights/resources.

Results are paginated with pagination.page and pagination.per_page (default 20, maximum 200) and can be sorted with pagination.sort and pagination.sort_direction. Optionally filter by filter.product_types and filter.regions.

A signal is omitted from a resource when no explicit enablement has ever been recorded for it.

Query Parameters

filter.product_types array of string optional
Example: ["droplet"]

Optional filter. When set, only resources of these product types are returned. Repeat the parameter for multiple product types.

filter.regions array of string optional
Example: ["nyc3"]

Optional filter. When set, only resources in these regions are returned. Repeat the parameter for multiple regions.

pagination.page integer >= 1 optional
Example: 1

Which 'page' of paginated results to return.

Default: 1
pagination.per_page integer 1 – 200 optional
Example: 20

Number of items returned per page.

Default: 20
pagination.sort string, one of: resource_urn, effective_at optional
Example: effective_at

Field to sort by. Defaults to resource_urn.

pagination.sort_direction string, one of: asc, desc optional
Example: desc

Sort direction. Defaults to asc.

Request: /v2/insights/resources
curl -X GET \
  -H "Authorization: Bearer $DIGITALOCEAN_TOKEN" \
  "https://api.digitalocean.com/v2/insights/resources?filter.product_types=droplet&pagination.per_page=50"

Responses

200

A paginated list of resources and their signal enablement.
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
pagination object optional

Page-based pagination metadata for a resources list.

Show child properties
page integer optional
Example: 1

The current page number.

pages integer optional
Example: 3

The total number of pages. Omitted when there are no results.

per_page integer optional
Example: 20

The number of items per page.

total integer optional
Example: 42

The total number of resources across all pages. Omitted when there are no results.

resources array of object optional

Resources with recorded signal enablement. Omitted when none match.

Show child properties
logs object optional

The enablement state of a single telemetry signal (metrics, logs, or traces) for a resource. A signal state is omitted from a resource when no explicit enablement has ever been recorded for that signal.

Show child properties
effective_at string (date-time) optional
Example: 2026-10-01T12:00:00Z

When this signal state last changed.

enabled boolean optional
Example: true

Whether the signal is enabled for the resource.

metrics object optional

The enablement state of a single telemetry signal (metrics, logs, or traces) for a resource. A signal state is omitted from a resource when no explicit enablement has ever been recorded for that signal.

Show child properties
effective_at string (date-time) optional
Example: 2026-10-01T12:00:00Z

When this signal state last changed.

enabled boolean optional
Example: true

Whether the signal is enabled for the resource.

product_type string required
Example: droplet

The product type of the resource, for example droplet or kubernetes.

region string optional
Example: nyc3

The region slug for region-specific resources. Omitted when the resource has no region.

resource_urn string required
Example: do:droplet:12345

The uniform resource name (URN) of the resource.

traces object optional

The enablement state of a single telemetry signal (metrics, logs, or traces) for a resource. A signal state is omitted from a resource when no explicit enablement has ever been recorded for that signal.

Show child properties
effective_at string (date-time) optional
Example: 2026-10-01T12:00:00Z

When this signal state last changed.

enabled boolean optional
Example: true

Whether the signal is enabled for the resource.

400

There was an error parsing the request body.
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.

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
{
  "pagination": {
    "page": 1,
    "pages": 1,
    "per_page": 20,
    "total": 2
  },
  "resources": [
    {
      "logs": {
        "effective_at": "2026-10-01T12:00:00Z",
        "enabled": true
      },
      "metrics": {
        "effective_at": "2026-10-01T12:00:00Z",
        "enabled": true
      },
      "product_type": "droplet",
      "region": "nyc3",
      "resource_urn": "do:droplet:12345",
      "traces": {
        "effective_at": "2026-10-03T08:30:00Z",
        "enabled": false
      }
    },
    {
      "metrics": {
        "effective_at": "2026-09-20T09:15:00Z",
        "enabled": true
      },
      "product_type": "kubernetes",
      "region": "sfo3",
      "resource_urn": "do:kubernetes:8d91d5e0-1c2b-4f3a-9e7d-6a5b4c3d2e1f"
    }
  ]
}
{
  "id": "bad_request",
  "message": "error parsing request body",
  "request_id": "4851a473-1621-42ea-b2f9-5071c0ea8414"
}
{
  "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 Resource Signal Enablement

/v2/insights/resources/{resource_urn}
Authorizations: bearer_auth (1 scope)
Http: Bearer
Required scopes: insights: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 retrieve the current metrics, logs, and traces signal enablement for a single resource, send a GET request to /v2/insights/resources/{resource_urn}.

A 404 is returned when no signal enablement has been recorded for the resource.

Path Parameters

resource_urn string required
Example: do:droplet:12345

The uniform resource name (URN) of the resource, for example do:droplet:12345.

Request: /v2/insights/resources/{resource_urn}
curl -X GET \
  -H "Authorization: Bearer $DIGITALOCEAN_TOKEN" \
  "https://api.digitalocean.com/v2/insights/resources/do:droplet:12345"

Responses

200

The resource's current signal enablement.
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
resource object required

The current telemetry signal enablement for a single resource.

Show child properties
logs object optional

The enablement state of a single telemetry signal (metrics, logs, or traces) for a resource. A signal state is omitted from a resource when no explicit enablement has ever been recorded for that signal.

Show child properties
effective_at string (date-time) optional
Example: 2026-10-01T12:00:00Z

When this signal state last changed.

enabled boolean optional
Example: true

Whether the signal is enabled for the resource.

metrics object optional

The enablement state of a single telemetry signal (metrics, logs, or traces) for a resource. A signal state is omitted from a resource when no explicit enablement has ever been recorded for that signal.

Show child properties
effective_at string (date-time) optional
Example: 2026-10-01T12:00:00Z

When this signal state last changed.

enabled boolean optional
Example: true

Whether the signal is enabled for the resource.

product_type string required
Example: droplet

The product type of the resource, for example droplet or kubernetes.

region string optional
Example: nyc3

The region slug for region-specific resources. Omitted when the resource has no region.

resource_urn string required
Example: do:droplet:12345

The uniform resource name (URN) of the resource.

traces object optional

The enablement state of a single telemetry signal (metrics, logs, or traces) for a resource. A signal state is omitted from a resource when no explicit enablement has ever been recorded for that signal.

Show child properties
effective_at string (date-time) optional
Example: 2026-10-01T12:00:00Z

When this signal state last changed.

enabled boolean optional
Example: true

Whether the signal is enabled for the resource.

400

There was an error parsing the request body.
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.

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
{
  "resource": {
    "logs": {
      "effective_at": "2026-10-01T12:00:00Z",
      "enabled": true
    },
    "metrics": {
      "effective_at": "2026-10-01T12:00:00Z",
      "enabled": true
    },
    "product_type": "droplet",
    "region": "nyc3",
    "resource_urn": "do:droplet:12345",
    "traces": {
      "effective_at": "2026-10-03T08:30:00Z",
      "enabled": false
    }
  }
}
{
  "id": "bad_request",
  "message": "error parsing request body",
  "request_id": "4851a473-1621-42ea-b2f9-5071c0ea8414"
}
{
  "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 Resource Signal Enablement

/v2/insights/resources/{resource_urn}/signals
Authorizations: bearer_auth (2 scopes)
Http: Bearer
Required scopes: insights:update insights: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 enable or disable telemetry signals for a resource, send a PUT request to /v2/insights/resources/{resource_urn}/signals.

This endpoint uses merge semantics. Set metrics, logs, or traces to true or false to change that signal; omit a signal to leave it unchanged. At least one signal must be set.

region is only used when the resource has no existing enablement. On later updates, omit it or send the stored value; changing the region is rejected with a 400.

Requires both the insights:update and insights:create scopes.

Path Parameters

resource_urn string required
Example: do:droplet:12345

The uniform resource name (URN) of the resource, for example do:droplet:12345.

Request Body: application/json

logs boolean optional
Example: true

Enable or disable the logs signal. Omit to leave unchanged.

metrics boolean optional
Example: true

Enable or disable the metrics signal. Omit to leave unchanged.

region string optional
Example: nyc3

The region slug for region-specific resources. Only used when the resource has no existing enablement. On later updates, omit it or send the stored value; changing the region is rejected.

traces boolean optional
Example: false

Enable or disable the traces signal. Omit to leave unchanged.

Request: /v2/insights/resources/{resource_urn}/signals
Content type application/json 
{
  "logs": true,
  "metrics": true,
  "region": "nyc3"
}
curl -X PUT \
  -H "Content-Type: application/json" \
  -H "Authorization: Bearer $DIGITALOCEAN_TOKEN" \
  -d '{"region":"nyc3","metrics":true,"logs":true}' \
  "https://api.digitalocean.com/v2/insights/resources/do:droplet:12345/signals"

Responses

200

The resource's current signal enablement.
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
resource object required

The current telemetry signal enablement for a single resource.

Show child properties
logs object optional

The enablement state of a single telemetry signal (metrics, logs, or traces) for a resource. A signal state is omitted from a resource when no explicit enablement has ever been recorded for that signal.

Show child properties
effective_at string (date-time) optional
Example: 2026-10-01T12:00:00Z

When this signal state last changed.

enabled boolean optional
Example: true

Whether the signal is enabled for the resource.

metrics object optional

The enablement state of a single telemetry signal (metrics, logs, or traces) for a resource. A signal state is omitted from a resource when no explicit enablement has ever been recorded for that signal.

Show child properties
effective_at string (date-time) optional
Example: 2026-10-01T12:00:00Z

When this signal state last changed.

enabled boolean optional
Example: true

Whether the signal is enabled for the resource.

product_type string required
Example: droplet

The product type of the resource, for example droplet or kubernetes.

region string optional
Example: nyc3

The region slug for region-specific resources. Omitted when the resource has no region.

resource_urn string required
Example: do:droplet:12345

The uniform resource name (URN) of the resource.

traces object optional

The enablement state of a single telemetry signal (metrics, logs, or traces) for a resource. A signal state is omitted from a resource when no explicit enablement has ever been recorded for that signal.

Show child properties
effective_at string (date-time) optional
Example: 2026-10-01T12:00:00Z

When this signal state last changed.

enabled boolean optional
Example: true

Whether the signal is enabled for the resource.

400

There was an error parsing the request body.
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.

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
{
  "resource": {
    "logs": {
      "effective_at": "2026-10-01T12:00:00Z",
      "enabled": true
    },
    "metrics": {
      "effective_at": "2026-10-01T12:00:00Z",
      "enabled": true
    },
    "product_type": "droplet",
    "region": "nyc3",
    "resource_urn": "do:droplet:12345",
    "traces": {
      "effective_at": "2026-10-03T08:30:00Z",
      "enabled": false
    }
  }
}
{
  "id": "bad_request",
  "message": "error parsing request body",
  "request_id": "4851a473-1621-42ea-b2f9-5071c0ea8414"
}
{
  "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.