DigitalOcean Insights API Reference

Last verified 1 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, and PromQL and logs query interfaces.

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 GET Execute a range PromQL query GET List label names GET List values for a label GET Find series by label selectors POST Search logs

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. webhook_url is write-only: send the full value on create/update; reads return a masked value (********). Omit webhook_url on update to keep the existing secret.

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

The Slack channel name to notify.

webhook_url string optional
Example: https://hooks.slack.com/services/T000/B000/XXXXXXXX

Slack incoming webhook URL. Write-only secret — full value on create/update; masked as ******** on read. Omit on update to retain the existing value.

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. The URL must use HTTPS and must not include userinfo. Optionally configure either basic_auth or bearer_token (not both), custom headers, and a signing secret.

url is not a secret and is returned in full on read. Credential fields (basic_auth.password, bearer_token.token, signature.secret) are write-only: full value on create/update; masked as ******** on read. Omit a secret field on update to keep the existing value.

Show child properties
basic_auth object optional

HTTP basic authentication credentials for a webhook. password is write-only: full value on create/update; masked (********) on read. Omit on update to keep the existing password.

Show child properties
password string (password) optional
Example: secret-password

Basic auth password. Write-only secret — full value on create/update; masked as ******** on read.

username string required
Example: webhook-user

Basic auth username.

bearer_token object optional

Bearer token authentication for a webhook. token is write-only: full value on create/update; masked (********) on read. Omit on update to keep the existing token.

Show child properties
token string (password) optional
Example: secret-token

Bearer token value sent in the Authorization header. Write-only secret — full value on create/update; masked as ******** on read.

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

Optional custom HTTP headers to include on webhook deliveries. At most 20 headers are allowed. Reserved header names such as host, content-type, and proxy-* are rejected.

signature object optional

Optional HMAC signature configuration. secret is write-only: full value on create/update; masked (********) on read. Omit on update to keep the existing secret.

Show child properties
secret string (password) optional
Example: whsec

Shared secret used to sign webhook payloads. Write-only secret — full value on create/update; masked as ******** on read.

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

HTTPS URL that receives webhook deliveries. Returned in full on read.

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 and returned masked on subsequent reads.

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. webhook_url is write-only: send the full value on create/update; reads return a masked value (********). Omit webhook_url on update to keep the existing secret.

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

The Slack channel name to notify.

webhook_url string optional
Example: https://hooks.slack.com/services/T000/B000/XXXXXXXX

Slack incoming webhook URL. Write-only secret — full value on create/update; masked as ******** on read. Omit on update to retain the existing value.

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. The URL must use HTTPS and must not include userinfo. Optionally configure either basic_auth or bearer_token (not both), custom headers, and a signing secret.

url is not a secret and is returned in full on read. Credential fields (basic_auth.password, bearer_token.token, signature.secret) are write-only: full value on create/update; masked as ******** on read. Omit a secret field on update to keep the existing value.

Show child properties
basic_auth object optional

HTTP basic authentication credentials for a webhook. password is write-only: full value on create/update; masked (********) on read. Omit on update to keep the existing password.

Show child properties
password string (password) optional
Example: secret-password

Basic auth password. Write-only secret — full value on create/update; masked as ******** on read.

username string required
Example: webhook-user

Basic auth username.

bearer_token object optional

Bearer token authentication for a webhook. token is write-only: full value on create/update; masked (********) on read. Omit on update to keep the existing token.

Show child properties
token string (password) optional
Example: secret-token

Bearer token value sent in the Authorization header. Write-only secret — full value on create/update; masked as ******** on read.

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

Optional custom HTTP headers to include on webhook deliveries. At most 20 headers are allowed. Reserved header names such as host, content-type, and proxy-* are rejected.

signature object optional

Optional HMAC signature configuration. secret is write-only: full value on create/update; masked (********) on read. Omit on update to keep the existing secret.

Show child properties
secret string (password) optional
Example: whsec

Shared secret used to sign webhook payloads. Write-only secret — full value on create/update; masked as ******** on read.

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

HTTPS URL that receives webhook deliveries. Returned in full on read.

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 fields are returned masked as ********.

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. webhook_url is write-only: send the full value on create/update; reads return a masked value (********). Omit webhook_url on update to keep the existing secret.

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

The Slack channel name to notify.

webhook_url string optional
Example: https://hooks.slack.com/services/T000/B000/XXXXXXXX

Slack incoming webhook URL. Write-only secret — full value on create/update; masked as ******** on read. Omit on update to retain the existing value.

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. The URL must use HTTPS and must not include userinfo. Optionally configure either basic_auth or bearer_token (not both), custom headers, and a signing secret.

url is not a secret and is returned in full on read. Credential fields (basic_auth.password, bearer_token.token, signature.secret) are write-only: full value on create/update; masked as ******** on read. Omit a secret field on update to keep the existing value.

Show child properties
basic_auth object optional

HTTP basic authentication credentials for a webhook. password is write-only: full value on create/update; masked (********) on read. Omit on update to keep the existing password.

Show child properties
password string (password) optional
Example: secret-password

Basic auth password. Write-only secret — full value on create/update; masked as ******** on read.

username string required
Example: webhook-user

Basic auth username.

bearer_token object optional

Bearer token authentication for a webhook. token is write-only: full value on create/update; masked (********) on read. Omit on update to keep the existing token.

Show child properties
token string (password) optional
Example: secret-token

Bearer token value sent in the Authorization header. Write-only secret — full value on create/update; masked as ******** on read.

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

Optional custom HTTP headers to include on webhook deliveries. At most 20 headers are allowed. Reserved header names such as host, content-type, and proxy-* are rejected.

signature object optional

Optional HMAC signature configuration. secret is write-only: full value on create/update; masked (********) on read. Omit on update to keep the existing secret.

Show child properties
secret string (password) optional
Example: whsec

Shared secret used to sign webhook payloads. Write-only secret — full value on create/update; masked as ******** on read.

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

HTTPS URL that receives webhook deliveries. Returned in full on read.

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.

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 
{
  "name": "Platform alerts (updated)",
  "slack": {
    "channel": "#platform-alerts-prod",
    "webhook_url": "https://hooks.slack.com/services/T000/B000/NEWTOKEN"
  }
}
curl -X PUT \
  -H "Content-Type: application/json" \
  -H "Authorization: Bearer $DIGITALOCEAN_TOKEN" \
  -d '{"name":"Platform alerts (updated)","slack":{"webhook_url":"https://hooks.slack.com/services/T000/B000/NEWTOKEN","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. webhook_url is write-only: send the full value on create/update; reads return a masked value (********). Omit webhook_url on update to keep the existing secret.

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

The Slack channel name to notify.

webhook_url string optional
Example: https://hooks.slack.com/services/T000/B000/XXXXXXXX

Slack incoming webhook URL. Write-only secret — full value on create/update; masked as ******** on read. Omit on update to retain the existing value.

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. The URL must use HTTPS and must not include userinfo. Optionally configure either basic_auth or bearer_token (not both), custom headers, and a signing secret.

url is not a secret and is returned in full on read. Credential fields (basic_auth.password, bearer_token.token, signature.secret) are write-only: full value on create/update; masked as ******** on read. Omit a secret field on update to keep the existing value.

Show child properties
basic_auth object optional

HTTP basic authentication credentials for a webhook. password is write-only: full value on create/update; masked (********) on read. Omit on update to keep the existing password.

Show child properties
password string (password) optional
Example: secret-password

Basic auth password. Write-only secret — full value on create/update; masked as ******** on read.

username string required
Example: webhook-user

Basic auth username.

bearer_token object optional

Bearer token authentication for a webhook. token is write-only: full value on create/update; masked (********) on read. Omit on update to keep the existing token.

Show child properties
token string (password) optional
Example: secret-token

Bearer token value sent in the Authorization header. Write-only secret — full value on create/update; masked as ******** on read.

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

Optional custom HTTP headers to include on webhook deliveries. At most 20 headers are allowed. Reserved header names such as host, content-type, and proxy-* are rejected.

signature object optional

Optional HMAC signature configuration. secret is write-only: full value on create/update; masked (********) on read. Omit on update to keep the existing secret.

Show child properties
secret string (password) optional
Example: whsec

Shared secret used to sign webhook payloads. Write-only secret — full value on create/update; masked as ******** on read.

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

HTTPS URL that receives webhook deliveries. Returned in full on read.

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"
}

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"
}

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"
}

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 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"
}

We can't find any results for your search.

Try using different keywords or simplifying your search terms.