--- title: DigitalOcean Insights API Reference product: Insights url: https://docs.digitalocean.com/reference/api/reference/insights/ --- > **For AI agents:** The documentation index is at [https://docs.digitalocean.com/llms.txt](https://docs.digitalocean.com/llms.txt). Markdown versions of pages use the same URL with `index.html.md` in place of the HTML page (for example, append `index.html.md` to the directory path instead of opening the HTML document). # DigitalOcean Insights API Reference [View full API reference](https://docs.digitalocean.com/reference/api/reference/index.html.md) 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](#insights_list_alertInstances) - **GET** [Retrieve an Alert Instance](#insights_get_alertInstance) - **GET** [List Alert Rules](#insights_list_alertRules) - **POST** [Create an Alert Rule](#insights_create_alertRule) - **GET** [Retrieve an Alert Rule](#insights_get_alertRule) - **PUT** [Update an Alert Rule](#insights_update_alertRule) - **DELETE** [Delete an Alert Rule](#insights_delete_alertRule) - **GET** [List Notification Channels](#insights_list_notificationChannels) - **POST** [Create a Notification Channel](#insights_create_notificationChannel) - **GET** [Retrieve a Notification Channel](#insights_get_notificationChannel) - **PUT** [Update a Notification Channel](#insights_update_notificationChannel) - **DELETE** [Delete a Notification Channel](#insights_delete_notificationChannel) - **GET** [Execute an instant PromQL query](#insights_get_promQuery) - **GET** [Execute a range PromQL query](#insights_get_promQueryRange) - **GET** [List label names](#insights_get_promLabels) - **GET** [List values for a label](#insights_get_promLabelValues) - **GET** [Find series by label selectors](#insights_get_promSeries) - **POST** [Search logs](#insights_post_logsSearch) ## 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](https://cloud.digitalocean.com/account/api/tokens) 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](https://docs.digitalocean.com/reference/api/oauth-api/index.html.md) - `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 | `:read` | | POST | Create | `:create` | | PUT/PATCH | Update | `:update` | | DELETE | Delete | `: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 ```bash 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](https://docs.digitalocean.com/reference/api/reference/index.html.md#rate-limit) for information about how requests expire. `ratelimit-reset` integer The time when the oldest request will expire. The value is given in Unix epoch time. See [https://docs.digitalocean.com/reference/api/reference/#rate-limit](https://docs.digitalocean.com/reference/api/reference/index.html.md#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](https://docs.digitalocean.com/reference/api/reference/index.html.md#rate-limit) for information about how requests expire. `ratelimit-reset` integer The time when the oldest request will expire. The value is given in Unix epoch time. See [https://docs.digitalocean.com/reference/api/reference/#rate-limit](https://docs.digitalocean.com/reference/api/reference/index.html.md#rate-limit) for information about how requests expire. Response Schema: `application/json` `id` string required Example: `not_found` A short identifier corresponding to the HTTP status code returned. For example, the ID for a response returning a 404 status code would be "not_found." `message` string required Example: `The resource you were accessing could not be found.` A message providing additional information about the error, including details to help resolve it when possible. `request_id` string optional Example: `4d9d8375-3c56-4925-a3e7-eb137fed17e9` 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](https://docs.digitalocean.com/reference/api/reference/index.html.md#rate-limit) for information about how requests expire. `ratelimit-reset` integer The time when the oldest request will expire. The value is given in Unix epoch time. See [https://docs.digitalocean.com/reference/api/reference/#rate-limit](https://docs.digitalocean.com/reference/api/reference/index.html.md#rate-limit) for information about how requests expire. Response Schema: `application/json` `id` string required Example: `not_found` A short identifier corresponding to the HTTP status code returned. For example, the ID for a response returning a 404 status code would be "not_found." `message` string required Example: `The resource you were accessing could not be found.` A message providing additional information about the error, including details to help resolve it when possible. `request_id` string optional Example: `4d9d8375-3c56-4925-a3e7-eb137fed17e9` 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](https://docs.digitalocean.com/reference/api/reference/index.html.md#rate-limit) for information about how requests expire. `ratelimit-reset` integer The time when the oldest request will expire. The value is given in Unix epoch time. See [https://docs.digitalocean.com/reference/api/reference/#rate-limit](https://docs.digitalocean.com/reference/api/reference/index.html.md#rate-limit) for information about how requests expire. Response Schema: `application/json` `id` string required Example: `not_found` A short identifier corresponding to the HTTP status code returned. For example, the ID for a response returning a 404 status code would be "not_found." `message` string required Example: `The resource you were accessing could not be found.` A message providing additional information about the error, including details to help resolve it when possible. `request_id` string optional Example: `4d9d8375-3c56-4925-a3e7-eb137fed17e9` 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](https://docs.digitalocean.com/reference/api/reference/index.html.md#rate-limit) for information about how requests expire. `ratelimit-reset` integer The time when the oldest request will expire. The value is given in Unix epoch time. See [https://docs.digitalocean.com/reference/api/reference/#rate-limit](https://docs.digitalocean.com/reference/api/reference/index.html.md#rate-limit) for information about how requests expire. Response Schema: `application/json` `id` string required Example: `not_found` A short identifier corresponding to the HTTP status code returned. For example, the ID for a response returning a 404 status code would be "not_found." `message` string required Example: `The resource you were accessing could not be found.` A message providing additional information about the error, including details to help resolve it when possible. `request_id` string optional Example: `4d9d8375-3c56-4925-a3e7-eb137fed17e9` 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](https://docs.digitalocean.com/reference/api/reference/index.html.md#rate-limit) for information about how requests expire. `ratelimit-reset` integer The time when the oldest request will expire. The value is given in Unix epoch time. See [https://docs.digitalocean.com/reference/api/reference/#rate-limit](https://docs.digitalocean.com/reference/api/reference/index.html.md#rate-limit) for information about how requests expire. Response Schema: `application/json` `id` string required Example: `not_found` A short identifier corresponding to the HTTP status code returned. For example, the ID for a response returning a 404 status code would be "not_found." `message` string required Example: `The resource you were accessing could not be found.` A message providing additional information about the error, including details to help resolve it when possible. `request_id` string optional Example: `4d9d8375-3c56-4925-a3e7-eb137fed17e9` 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 **200** ```json { "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 } } ``` **400** ```json { "id": "bad_request", "message": "error parsing request body", "request_id": "4851a473-1621-42ea-b2f9-5071c0ea8414" } ``` **401** ```json { "id": "unauthorized", "message": "Unable to authenticate you." } ``` **429** ```json { "id": "too_many_requests", "message": "API rate limit exceeded." } ``` **500** ```json { "id": "server_error", "message": "Unexpected server-side error" } ``` **default** ```json { "id": "example_error", "message": "some error message" } ``` * * * ## GET Retrieve an Alert Instance `/v2/insights/alert-instances/{id}` 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 ```bash 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](https://docs.digitalocean.com/reference/api/reference/index.html.md#rate-limit) for information about how requests expire. `ratelimit-reset` integer The time when the oldest request will expire. The value is given in Unix epoch time. See [https://docs.digitalocean.com/reference/api/reference/#rate-limit](https://docs.digitalocean.com/reference/api/reference/index.html.md#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](https://docs.digitalocean.com/reference/api/reference/index.html.md#rate-limit) for information about how requests expire. `ratelimit-reset` integer The time when the oldest request will expire. The value is given in Unix epoch time. See [https://docs.digitalocean.com/reference/api/reference/#rate-limit](https://docs.digitalocean.com/reference/api/reference/index.html.md#rate-limit) for information about how requests expire. Response Schema: `application/json` `id` string required Example: `not_found` A short identifier corresponding to the HTTP status code returned. For example, the ID for a response returning a 404 status code would be "not_found." `message` string required Example: `The resource you were accessing could not be found.` A message providing additional information about the error, including details to help resolve it when possible. `request_id` string optional Example: `4d9d8375-3c56-4925-a3e7-eb137fed17e9` 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](https://docs.digitalocean.com/reference/api/reference/index.html.md#rate-limit) for information about how requests expire. `ratelimit-reset` integer The time when the oldest request will expire. The value is given in Unix epoch time. See [https://docs.digitalocean.com/reference/api/reference/#rate-limit](https://docs.digitalocean.com/reference/api/reference/index.html.md#rate-limit) for information about how requests expire. Response Schema: `application/json` `id` string required Example: `not_found` A short identifier corresponding to the HTTP status code returned. For example, the ID for a response returning a 404 status code would be "not_found." `message` string required Example: `The resource you were accessing could not be found.` A message providing additional information about the error, including details to help resolve it when possible. `request_id` string optional Example: `4d9d8375-3c56-4925-a3e7-eb137fed17e9` 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](https://docs.digitalocean.com/reference/api/reference/index.html.md#rate-limit) for information about how requests expire. `ratelimit-reset` integer The time when the oldest request will expire. The value is given in Unix epoch time. See [https://docs.digitalocean.com/reference/api/reference/#rate-limit](https://docs.digitalocean.com/reference/api/reference/index.html.md#rate-limit) for information about how requests expire. Response Schema: `application/json` `id` string required Example: `not_found` A short identifier corresponding to the HTTP status code returned. For example, the ID for a response returning a 404 status code would be "not_found." `message` string required Example: `The resource you were accessing could not be found.` A message providing additional information about the error, including details to help resolve it when possible. `request_id` string optional Example: `4d9d8375-3c56-4925-a3e7-eb137fed17e9` 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](https://docs.digitalocean.com/reference/api/reference/index.html.md#rate-limit) for information about how requests expire. `ratelimit-reset` integer The time when the oldest request will expire. The value is given in Unix epoch time. See [https://docs.digitalocean.com/reference/api/reference/#rate-limit](https://docs.digitalocean.com/reference/api/reference/index.html.md#rate-limit) for information about how requests expire. Response Schema: `application/json` `id` string required Example: `not_found` A short identifier corresponding to the HTTP status code returned. For example, the ID for a response returning a 404 status code would be "not_found." `message` string required Example: `The resource you were accessing could not be found.` A message providing additional information about the error, including details to help resolve it when possible. `request_id` string optional Example: `4d9d8375-3c56-4925-a3e7-eb137fed17e9` 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](https://docs.digitalocean.com/reference/api/reference/index.html.md#rate-limit) for information about how requests expire. `ratelimit-reset` integer The time when the oldest request will expire. The value is given in Unix epoch time. See [https://docs.digitalocean.com/reference/api/reference/#rate-limit](https://docs.digitalocean.com/reference/api/reference/index.html.md#rate-limit) for information about how requests expire. Response Schema: `application/json` `id` string required Example: `not_found` A short identifier corresponding to the HTTP status code returned. For example, the ID for a response returning a 404 status code would be "not_found." `message` string required Example: `The resource you were accessing could not be found.` A message providing additional information about the error, including details to help resolve it when possible. `request_id` string optional Example: `4d9d8375-3c56-4925-a3e7-eb137fed17e9` 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 **200** ```json { "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 } } ``` **401** ```json { "id": "unauthorized", "message": "Unable to authenticate you." } ``` **404** ```json { "id": "not_found", "message": "The resource you requested could not be found." } ``` **429** ```json { "id": "too_many_requests", "message": "API rate limit exceeded." } ``` **500** ```json { "id": "server_error", "message": "Unexpected server-side error" } ``` **default** ```json { "id": "example_error", "message": "some error message" } ``` * * * ## GET List Alert Rules `/v2/insights/alert-rules` 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 ```bash 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](https://docs.digitalocean.com/reference/api/reference/index.html.md#rate-limit) for information about how requests expire. `ratelimit-reset` integer The time when the oldest request will expire. The value is given in Unix epoch time. See [https://docs.digitalocean.com/reference/api/reference/#rate-limit](https://docs.digitalocean.com/reference/api/reference/index.html.md#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](https://github.com/digitalocean/openapi) 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](https://docs.digitalocean.com/reference/api/reference/index.html.md#rate-limit) for information about how requests expire. `ratelimit-reset` integer The time when the oldest request will expire. The value is given in Unix epoch time. See [https://docs.digitalocean.com/reference/api/reference/#rate-limit](https://docs.digitalocean.com/reference/api/reference/index.html.md#rate-limit) for information about how requests expire. Response Schema: `application/json` `id` string required Example: `not_found` A short identifier corresponding to the HTTP status code returned. For example, the ID for a response returning a 404 status code would be "not_found." `message` string required Example: `The resource you were accessing could not be found.` A message providing additional information about the error, including details to help resolve it when possible. `request_id` string optional Example: `4d9d8375-3c56-4925-a3e7-eb137fed17e9` 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](https://docs.digitalocean.com/reference/api/reference/index.html.md#rate-limit) for information about how requests expire. `ratelimit-reset` integer The time when the oldest request will expire. The value is given in Unix epoch time. See [https://docs.digitalocean.com/reference/api/reference/#rate-limit](https://docs.digitalocean.com/reference/api/reference/index.html.md#rate-limit) for information about how requests expire. Response Schema: `application/json` `id` string required Example: `not_found` A short identifier corresponding to the HTTP status code returned. For example, the ID for a response returning a 404 status code would be "not_found." `message` string required Example: `The resource you were accessing could not be found.` A message providing additional information about the error, including details to help resolve it when possible. `request_id` string optional Example: `4d9d8375-3c56-4925-a3e7-eb137fed17e9` 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](https://docs.digitalocean.com/reference/api/reference/index.html.md#rate-limit) for information about how requests expire. `ratelimit-reset` integer The time when the oldest request will expire. The value is given in Unix epoch time. See [https://docs.digitalocean.com/reference/api/reference/#rate-limit](https://docs.digitalocean.com/reference/api/reference/index.html.md#rate-limit) for information about how requests expire. Response Schema: `application/json` `id` string required Example: `not_found` A short identifier corresponding to the HTTP status code returned. For example, the ID for a response returning a 404 status code would be "not_found." `message` string required Example: `The resource you were accessing could not be found.` A message providing additional information about the error, including details to help resolve it when possible. `request_id` string optional Example: `4d9d8375-3c56-4925-a3e7-eb137fed17e9` 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](https://docs.digitalocean.com/reference/api/reference/index.html.md#rate-limit) for information about how requests expire. `ratelimit-reset` integer The time when the oldest request will expire. The value is given in Unix epoch time. See [https://docs.digitalocean.com/reference/api/reference/#rate-limit](https://docs.digitalocean.com/reference/api/reference/index.html.md#rate-limit) for information about how requests expire. Response Schema: `application/json` `id` string required Example: `not_found` A short identifier corresponding to the HTTP status code returned. For example, the ID for a response returning a 404 status code would be "not_found." `message` string required Example: `The resource you were accessing could not be found.` A message providing additional information about the error, including details to help resolve it when possible. `request_id` string optional Example: `4d9d8375-3c56-4925-a3e7-eb137fed17e9` 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 **200** ```json { "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 } } ``` **401** ```json { "id": "unauthorized", "message": "Unable to authenticate you." } ``` **429** ```json { "id": "too_many_requests", "message": "API rate limit exceeded." } ``` **500** ```json { "id": "server_error", "message": "Unexpected server-side error" } ``` **default** ```json { "id": "example_error", "message": "some error message" } ``` * * * ## POST Create an Alert Rule `/v2/insights/alert-rules` 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` ### Payload Content type `application/json` ```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 ```bash 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](https://docs.digitalocean.com/reference/api/reference/index.html.md#rate-limit) for information about how requests expire. `ratelimit-reset` integer The time when the oldest request will expire. The value is given in Unix epoch time. See [https://docs.digitalocean.com/reference/api/reference/#rate-limit](https://docs.digitalocean.com/reference/api/reference/index.html.md#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](https://github.com/digitalocean/openapi) 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](https://docs.digitalocean.com/reference/api/reference/index.html.md#rate-limit) for information about how requests expire. `ratelimit-reset` integer The time when the oldest request will expire. The value is given in Unix epoch time. See [https://docs.digitalocean.com/reference/api/reference/#rate-limit](https://docs.digitalocean.com/reference/api/reference/index.html.md#rate-limit) for information about how requests expire. Response Schema: `application/json` `id` string required Example: `not_found` A short identifier corresponding to the HTTP status code returned. For example, the ID for a response returning a 404 status code would be "not_found." `message` string required Example: `The resource you were accessing could not be found.` A message providing additional information about the error, including details to help resolve it when possible. `request_id` string optional Example: `4d9d8375-3c56-4925-a3e7-eb137fed17e9` 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](https://docs.digitalocean.com/reference/api/reference/index.html.md#rate-limit) for information about how requests expire. `ratelimit-reset` integer The time when the oldest request will expire. The value is given in Unix epoch time. See [https://docs.digitalocean.com/reference/api/reference/#rate-limit](https://docs.digitalocean.com/reference/api/reference/index.html.md#rate-limit) for information about how requests expire. Response Schema: `application/json` `id` string required Example: `not_found` A short identifier corresponding to the HTTP status code returned. For example, the ID for a response returning a 404 status code would be "not_found." `message` string required Example: `The resource you were accessing could not be found.` A message providing additional information about the error, including details to help resolve it when possible. `request_id` string optional Example: `4d9d8375-3c56-4925-a3e7-eb137fed17e9` 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](https://docs.digitalocean.com/reference/api/reference/index.html.md#rate-limit) for information about how requests expire. `ratelimit-reset` integer The time when the oldest request will expire. The value is given in Unix epoch time. See [https://docs.digitalocean.com/reference/api/reference/#rate-limit](https://docs.digitalocean.com/reference/api/reference/index.html.md#rate-limit) for information about how requests expire. Response Schema: `application/json` `id` string required Example: `not_found` A short identifier corresponding to the HTTP status code returned. For example, the ID for a response returning a 404 status code would be "not_found." `message` string required Example: `The resource you were accessing could not be found.` A message providing additional information about the error, including details to help resolve it when possible. `request_id` string optional Example: `4d9d8375-3c56-4925-a3e7-eb137fed17e9` 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](https://docs.digitalocean.com/reference/api/reference/index.html.md#rate-limit) for information about how requests expire. `ratelimit-reset` integer The time when the oldest request will expire. The value is given in Unix epoch time. See [https://docs.digitalocean.com/reference/api/reference/#rate-limit](https://docs.digitalocean.com/reference/api/reference/index.html.md#rate-limit) for information about how requests expire. Response Schema: `application/json` `id` string required Example: `not_found` A short identifier corresponding to the HTTP status code returned. For example, the ID for a response returning a 404 status code would be "not_found." `message` string required Example: `The resource you were accessing could not be found.` A message providing additional information about the error, including details to help resolve it when possible. `request_id` string optional Example: `4d9d8375-3c56-4925-a3e7-eb137fed17e9` 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](https://docs.digitalocean.com/reference/api/reference/index.html.md#rate-limit) for information about how requests expire. `ratelimit-reset` integer The time when the oldest request will expire. The value is given in Unix epoch time. See [https://docs.digitalocean.com/reference/api/reference/#rate-limit](https://docs.digitalocean.com/reference/api/reference/index.html.md#rate-limit) for information about how requests expire. Response Schema: `application/json` `id` string required Example: `not_found` A short identifier corresponding to the HTTP status code returned. For example, the ID for a response returning a 404 status code would be "not_found." `message` string required Example: `The resource you were accessing could not be found.` A message providing additional information about the error, including details to help resolve it when possible. `request_id` string optional Example: `4d9d8375-3c56-4925-a3e7-eb137fed17e9` 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](https://docs.digitalocean.com/reference/api/reference/index.html.md#rate-limit) for information about how requests expire. `ratelimit-reset` integer The time when the oldest request will expire. The value is given in Unix epoch time. See [https://docs.digitalocean.com/reference/api/reference/#rate-limit](https://docs.digitalocean.com/reference/api/reference/index.html.md#rate-limit) for information about how requests expire. Response Schema: `application/json` `id` string required Example: `not_found` A short identifier corresponding to the HTTP status code returned. For example, the ID for a response returning a 404 status code would be "not_found." `message` string required Example: `The resource you were accessing could not be found.` A message providing additional information about the error, including details to help resolve it when possible. `request_id` string optional Example: `4d9d8375-3c56-4925-a3e7-eb137fed17e9` 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 **201** ```json { "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" } } ``` **400** ```json { "id": "bad_request", "message": "error parsing request body", "request_id": "4851a473-1621-42ea-b2f9-5071c0ea8414" } ``` **401** ```json { "id": "unauthorized", "message": "Unable to authenticate you." } ``` **422** ```json { "id": "unprocessable_entity", "message": "request payload validation failed", "request_id": "4851a473-1621-42ea-b2f9-5071c0ea8414" } ``` **429** ```json { "id": "too_many_requests", "message": "API rate limit exceeded." } ``` **500** ```json { "id": "server_error", "message": "Unexpected server-side error" } ``` **default** ```json { "id": "example_error", "message": "some error message" } ``` * * * ## GET Retrieve an Alert Rule `/v2/insights/alert-rules/{id}` 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 ```bash 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](https://docs.digitalocean.com/reference/api/reference/index.html.md#rate-limit) for information about how requests expire. `ratelimit-reset` integer The time when the oldest request will expire. The value is given in Unix epoch time. See [https://docs.digitalocean.com/reference/api/reference/#rate-limit](https://docs.digitalocean.com/reference/api/reference/index.html.md#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](https://github.com/digitalocean/openapi) 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](https://docs.digitalocean.com/reference/api/reference/index.html.md#rate-limit) for information about how requests expire. `ratelimit-reset` integer The time when the oldest request will expire. The value is given in Unix epoch time. See [https://docs.digitalocean.com/reference/api/reference/#rate-limit](https://docs.digitalocean.com/reference/api/reference/index.html.md#rate-limit) for information about how requests expire. Response Schema: `application/json` `id` string required Example: `not_found` A short identifier corresponding to the HTTP status code returned. For example, the ID for a response returning a 404 status code would be "not_found." `message` string required Example: `The resource you were accessing could not be found.` A message providing additional information about the error, including details to help resolve it when possible. `request_id` string optional Example: `4d9d8375-3c56-4925-a3e7-eb137fed17e9` 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](https://docs.digitalocean.com/reference/api/reference/index.html.md#rate-limit) for information about how requests expire. `ratelimit-reset` integer The time when the oldest request will expire. The value is given in Unix epoch time. See [https://docs.digitalocean.com/reference/api/reference/#rate-limit](https://docs.digitalocean.com/reference/api/reference/index.html.md#rate-limit) for information about how requests expire. Response Schema: `application/json` `id` string required Example: `not_found` A short identifier corresponding to the HTTP status code returned. For example, the ID for a response returning a 404 status code would be "not_found." `message` string required Example: `The resource you were accessing could not be found.` A message providing additional information about the error, including details to help resolve it when possible. `request_id` string optional Example: `4d9d8375-3c56-4925-a3e7-eb137fed17e9` 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](https://docs.digitalocean.com/reference/api/reference/index.html.md#rate-limit) for information about how requests expire. `ratelimit-reset` integer The time when the oldest request will expire. The value is given in Unix epoch time. See [https://docs.digitalocean.com/reference/api/reference/#rate-limit](https://docs.digitalocean.com/reference/api/reference/index.html.md#rate-limit) for information about how requests expire. Response Schema: `application/json` `id` string required Example: `not_found` A short identifier corresponding to the HTTP status code returned. For example, the ID for a response returning a 404 status code would be "not_found." `message` string required Example: `The resource you were accessing could not be found.` A message providing additional information about the error, including details to help resolve it when possible. `request_id` string optional Example: `4d9d8375-3c56-4925-a3e7-eb137fed17e9` 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](https://docs.digitalocean.com/reference/api/reference/index.html.md#rate-limit) for information about how requests expire. `ratelimit-reset` integer The time when the oldest request will expire. The value is given in Unix epoch time. See [https://docs.digitalocean.com/reference/api/reference/#rate-limit](https://docs.digitalocean.com/reference/api/reference/index.html.md#rate-limit) for information about how requests expire. Response Schema: `application/json` `id` string required Example: `not_found` A short identifier corresponding to the HTTP status code returned. For example, the ID for a response returning a 404 status code would be "not_found." `message` string required Example: `The resource you were accessing could not be found.` A message providing additional information about the error, including details to help resolve it when possible. `request_id` string optional Example: `4d9d8375-3c56-4925-a3e7-eb137fed17e9` 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](https://docs.digitalocean.com/reference/api/reference/index.html.md#rate-limit) for information about how requests expire. `ratelimit-reset` integer The time when the oldest request will expire. The value is given in Unix epoch time. See [https://docs.digitalocean.com/reference/api/reference/#rate-limit](https://docs.digitalocean.com/reference/api/reference/index.html.md#rate-limit) for information about how requests expire. Response Schema: `application/json` `id` string required Example: `not_found` A short identifier corresponding to the HTTP status code returned. For example, the ID for a response returning a 404 status code would be "not_found." `message` string required Example: `The resource you were accessing could not be found.` A message providing additional information about the error, including details to help resolve it when possible. `request_id` string optional Example: `4d9d8375-3c56-4925-a3e7-eb137fed17e9` 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 **200** ```json { "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" } } ``` **401** ```json { "id": "unauthorized", "message": "Unable to authenticate you." } ``` **404** ```json { "id": "not_found", "message": "The resource you requested could not be found." } ``` **429** ```json { "id": "too_many_requests", "message": "API rate limit exceeded." } ``` **500** ```json { "id": "server_error", "message": "Unexpected server-side error" } ``` **default** ```json { "id": "example_error", "message": "some error message" } ``` * * * ## PUT Update an Alert Rule `/v2/insights/alert-rules/{id}` 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}` ### Payload Content type `application/json` ```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 ```bash 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](https://docs.digitalocean.com/reference/api/reference/index.html.md#rate-limit) for information about how requests expire. `ratelimit-reset` integer The time when the oldest request will expire. The value is given in Unix epoch time. See [https://docs.digitalocean.com/reference/api/reference/#rate-limit](https://docs.digitalocean.com/reference/api/reference/index.html.md#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](https://github.com/digitalocean/openapi) 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](https://docs.digitalocean.com/reference/api/reference/index.html.md#rate-limit) for information about how requests expire. `ratelimit-reset` integer The time when the oldest request will expire. The value is given in Unix epoch time. See [https://docs.digitalocean.com/reference/api/reference/#rate-limit](https://docs.digitalocean.com/reference/api/reference/index.html.md#rate-limit) for information about how requests expire. Response Schema: `application/json` `id` string required Example: `not_found` A short identifier corresponding to the HTTP status code returned. For example, the ID for a response returning a 404 status code would be "not_found." `message` string required Example: `The resource you were accessing could not be found.` A message providing additional information about the error, including details to help resolve it when possible. `request_id` string optional Example: `4d9d8375-3c56-4925-a3e7-eb137fed17e9` 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](https://docs.digitalocean.com/reference/api/reference/index.html.md#rate-limit) for information about how requests expire. `ratelimit-reset` integer The time when the oldest request will expire. The value is given in Unix epoch time. See [https://docs.digitalocean.com/reference/api/reference/#rate-limit](https://docs.digitalocean.com/reference/api/reference/index.html.md#rate-limit) for information about how requests expire. Response Schema: `application/json` `id` string required Example: `not_found` A short identifier corresponding to the HTTP status code returned. For example, the ID for a response returning a 404 status code would be "not_found." `message` string required Example: `The resource you were accessing could not be found.` A message providing additional information about the error, including details to help resolve it when possible. `request_id` string optional Example: `4d9d8375-3c56-4925-a3e7-eb137fed17e9` 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](https://docs.digitalocean.com/reference/api/reference/index.html.md#rate-limit) for information about how requests expire. `ratelimit-reset` integer The time when the oldest request will expire. The value is given in Unix epoch time. See [https://docs.digitalocean.com/reference/api/reference/#rate-limit](https://docs.digitalocean.com/reference/api/reference/index.html.md#rate-limit) for information about how requests expire. Response Schema: `application/json` `id` string required Example: `not_found` A short identifier corresponding to the HTTP status code returned. For example, the ID for a response returning a 404 status code would be "not_found." `message` string required Example: `The resource you were accessing could not be found.` A message providing additional information about the error, including details to help resolve it when possible. `request_id` string optional Example: `4d9d8375-3c56-4925-a3e7-eb137fed17e9` 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](https://docs.digitalocean.com/reference/api/reference/index.html.md#rate-limit) for information about how requests expire. `ratelimit-reset` integer The time when the oldest request will expire. The value is given in Unix epoch time. See [https://docs.digitalocean.com/reference/api/reference/#rate-limit](https://docs.digitalocean.com/reference/api/reference/index.html.md#rate-limit) for information about how requests expire. Response Schema: `application/json` `id` string required Example: `not_found` A short identifier corresponding to the HTTP status code returned. For example, the ID for a response returning a 404 status code would be "not_found." `message` string required Example: `The resource you were accessing could not be found.` A message providing additional information about the error, including details to help resolve it when possible. `request_id` string optional Example: `4d9d8375-3c56-4925-a3e7-eb137fed17e9` 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](https://docs.digitalocean.com/reference/api/reference/index.html.md#rate-limit) for information about how requests expire. `ratelimit-reset` integer The time when the oldest request will expire. The value is given in Unix epoch time. See [https://docs.digitalocean.com/reference/api/reference/#rate-limit](https://docs.digitalocean.com/reference/api/reference/index.html.md#rate-limit) for information about how requests expire. Response Schema: `application/json` `id` string required Example: `not_found` A short identifier corresponding to the HTTP status code returned. For example, the ID for a response returning a 404 status code would be "not_found." `message` string required Example: `The resource you were accessing could not be found.` A message providing additional information about the error, including details to help resolve it when possible. `request_id` string optional Example: `4d9d8375-3c56-4925-a3e7-eb137fed17e9` 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](https://docs.digitalocean.com/reference/api/reference/index.html.md#rate-limit) for information about how requests expire. `ratelimit-reset` integer The time when the oldest request will expire. The value is given in Unix epoch time. See [https://docs.digitalocean.com/reference/api/reference/#rate-limit](https://docs.digitalocean.com/reference/api/reference/index.html.md#rate-limit) for information about how requests expire. Response Schema: `application/json` `id` string required Example: `not_found` A short identifier corresponding to the HTTP status code returned. For example, the ID for a response returning a 404 status code would be "not_found." `message` string required Example: `The resource you were accessing could not be found.` A message providing additional information about the error, including details to help resolve it when possible. `request_id` string optional Example: `4d9d8375-3c56-4925-a3e7-eb137fed17e9` 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](https://docs.digitalocean.com/reference/api/reference/index.html.md#rate-limit) for information about how requests expire. `ratelimit-reset` integer The time when the oldest request will expire. The value is given in Unix epoch time. See [https://docs.digitalocean.com/reference/api/reference/#rate-limit](https://docs.digitalocean.com/reference/api/reference/index.html.md#rate-limit) for information about how requests expire. Response Schema: `application/json` `id` string required Example: `not_found` A short identifier corresponding to the HTTP status code returned. For example, the ID for a response returning a 404 status code would be "not_found." `message` string required Example: `The resource you were accessing could not be found.` A message providing additional information about the error, including details to help resolve it when possible. `request_id` string optional Example: `4d9d8375-3c56-4925-a3e7-eb137fed17e9` 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 **200** ```json { "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" } } ``` **400** ```json { "id": "bad_request", "message": "error parsing request body", "request_id": "4851a473-1621-42ea-b2f9-5071c0ea8414" } ``` **401** ```json { "id": "unauthorized", "message": "Unable to authenticate you." } ``` **404** ```json { "id": "not_found", "message": "The resource you requested could not be found." } ``` **422** ```json { "id": "unprocessable_entity", "message": "request payload validation failed", "request_id": "4851a473-1621-42ea-b2f9-5071c0ea8414" } ``` **429** ```json { "id": "too_many_requests", "message": "API rate limit exceeded." } ``` **500** ```json { "id": "server_error", "message": "Unexpected server-side error" } ``` **default** ```json { "id": "example_error", "message": "some error message" } ``` * * * ## DELETE Delete an Alert Rule `/v2/insights/alert-rules/{id}` 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 ```bash 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](https://docs.digitalocean.com/reference/api/reference/index.html.md#rate-limit) for information about how requests expire. `ratelimit-reset` integer The time when the oldest request will expire. The value is given in Unix epoch time. See [https://docs.digitalocean.com/reference/api/reference/#rate-limit](https://docs.digitalocean.com/reference/api/reference/index.html.md#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](https://docs.digitalocean.com/reference/api/reference/index.html.md#rate-limit) for information about how requests expire. `ratelimit-reset` integer The time when the oldest request will expire. The value is given in Unix epoch time. See [https://docs.digitalocean.com/reference/api/reference/#rate-limit](https://docs.digitalocean.com/reference/api/reference/index.html.md#rate-limit) for information about how requests expire. Response Schema: `application/json` `id` string required Example: `not_found` A short identifier corresponding to the HTTP status code returned. For example, the ID for a response returning a 404 status code would be "not_found." `message` string required Example: `The resource you were accessing could not be found.` A message providing additional information about the error, including details to help resolve it when possible. `request_id` string optional Example: `4d9d8375-3c56-4925-a3e7-eb137fed17e9` 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](https://docs.digitalocean.com/reference/api/reference/index.html.md#rate-limit) for information about how requests expire. `ratelimit-reset` integer The time when the oldest request will expire. The value is given in Unix epoch time. See [https://docs.digitalocean.com/reference/api/reference/#rate-limit](https://docs.digitalocean.com/reference/api/reference/index.html.md#rate-limit) for information about how requests expire. Response Schema: `application/json` `id` string required Example: `not_found` A short identifier corresponding to the HTTP status code returned. For example, the ID for a response returning a 404 status code would be "not_found." `message` string required Example: `The resource you were accessing could not be found.` A message providing additional information about the error, including details to help resolve it when possible. `request_id` string optional Example: `4d9d8375-3c56-4925-a3e7-eb137fed17e9` 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](https://docs.digitalocean.com/reference/api/reference/index.html.md#rate-limit) for information about how requests expire. `ratelimit-reset` integer The time when the oldest request will expire. The value is given in Unix epoch time. See [https://docs.digitalocean.com/reference/api/reference/#rate-limit](https://docs.digitalocean.com/reference/api/reference/index.html.md#rate-limit) for information about how requests expire. Response Schema: `application/json` `id` string required Example: `not_found` A short identifier corresponding to the HTTP status code returned. For example, the ID for a response returning a 404 status code would be "not_found." `message` string required Example: `The resource you were accessing could not be found.` A message providing additional information about the error, including details to help resolve it when possible. `request_id` string optional Example: `4d9d8375-3c56-4925-a3e7-eb137fed17e9` 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](https://docs.digitalocean.com/reference/api/reference/index.html.md#rate-limit) for information about how requests expire. `ratelimit-reset` integer The time when the oldest request will expire. The value is given in Unix epoch time. See [https://docs.digitalocean.com/reference/api/reference/#rate-limit](https://docs.digitalocean.com/reference/api/reference/index.html.md#rate-limit) for information about how requests expire. Response Schema: `application/json` `id` string required Example: `not_found` A short identifier corresponding to the HTTP status code returned. For example, the ID for a response returning a 404 status code would be "not_found." `message` string required Example: `The resource you were accessing could not be found.` A message providing additional information about the error, including details to help resolve it when possible. `request_id` string optional Example: `4d9d8375-3c56-4925-a3e7-eb137fed17e9` 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](https://docs.digitalocean.com/reference/api/reference/index.html.md#rate-limit) for information about how requests expire. `ratelimit-reset` integer The time when the oldest request will expire. The value is given in Unix epoch time. See [https://docs.digitalocean.com/reference/api/reference/#rate-limit](https://docs.digitalocean.com/reference/api/reference/index.html.md#rate-limit) for information about how requests expire. Response Schema: `application/json` `id` string required Example: `not_found` A short identifier corresponding to the HTTP status code returned. For example, the ID for a response returning a 404 status code would be "not_found." `message` string required Example: `The resource you were accessing could not be found.` A message providing additional information about the error, including details to help resolve it when possible. `request_id` string optional Example: `4d9d8375-3c56-4925-a3e7-eb137fed17e9` 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 **401** ```json { "id": "unauthorized", "message": "Unable to authenticate you." } ``` **404** ```json { "id": "not_found", "message": "The resource you requested could not be found." } ``` **429** ```json { "id": "too_many_requests", "message": "API rate limit exceeded." } ``` **500** ```json { "id": "server_error", "message": "Unexpected server-side error" } ``` **default** ```json { "id": "example_error", "message": "some error message" } ``` * * * ## GET List Notification Channels `/v2/insights/notification-channels` 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 ```bash 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](https://docs.digitalocean.com/reference/api/reference/index.html.md#rate-limit) for information about how requests expire. `ratelimit-reset` integer The time when the oldest request will expire. The value is given in Unix epoch time. See [https://docs.digitalocean.com/reference/api/reference/#rate-limit](https://docs.digitalocean.com/reference/api/reference/index.html.md#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: `alerts@example.com, backup@example.com` 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](https://docs.digitalocean.com/reference/api/reference/index.html.md#rate-limit) for information about how requests expire. `ratelimit-reset` integer The time when the oldest request will expire. The value is given in Unix epoch time. See [https://docs.digitalocean.com/reference/api/reference/#rate-limit](https://docs.digitalocean.com/reference/api/reference/index.html.md#rate-limit) for information about how requests expire. Response Schema: `application/json` `id` string required Example: `not_found` A short identifier corresponding to the HTTP status code returned. For example, the ID for a response returning a 404 status code would be "not_found." `message` string required Example: `The resource you were accessing could not be found.` A message providing additional information about the error, including details to help resolve it when possible. `request_id` string optional Example: `4d9d8375-3c56-4925-a3e7-eb137fed17e9` 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](https://docs.digitalocean.com/reference/api/reference/index.html.md#rate-limit) for information about how requests expire. `ratelimit-reset` integer The time when the oldest request will expire. The value is given in Unix epoch time. See [https://docs.digitalocean.com/reference/api/reference/#rate-limit](https://docs.digitalocean.com/reference/api/reference/index.html.md#rate-limit) for information about how requests expire. Response Schema: `application/json` `id` string required Example: `not_found` A short identifier corresponding to the HTTP status code returned. For example, the ID for a response returning a 404 status code would be "not_found." `message` string required Example: `The resource you were accessing could not be found.` A message providing additional information about the error, including details to help resolve it when possible. `request_id` string optional Example: `4d9d8375-3c56-4925-a3e7-eb137fed17e9` 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](https://docs.digitalocean.com/reference/api/reference/index.html.md#rate-limit) for information about how requests expire. `ratelimit-reset` integer The time when the oldest request will expire. The value is given in Unix epoch time. See [https://docs.digitalocean.com/reference/api/reference/#rate-limit](https://docs.digitalocean.com/reference/api/reference/index.html.md#rate-limit) for information about how requests expire. Response Schema: `application/json` `id` string required Example: `not_found` A short identifier corresponding to the HTTP status code returned. For example, the ID for a response returning a 404 status code would be "not_found." `message` string required Example: `The resource you were accessing could not be found.` A message providing additional information about the error, including details to help resolve it when possible. `request_id` string optional Example: `4d9d8375-3c56-4925-a3e7-eb137fed17e9` 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](https://docs.digitalocean.com/reference/api/reference/index.html.md#rate-limit) for information about how requests expire. `ratelimit-reset` integer The time when the oldest request will expire. The value is given in Unix epoch time. See [https://docs.digitalocean.com/reference/api/reference/#rate-limit](https://docs.digitalocean.com/reference/api/reference/index.html.md#rate-limit) for information about how requests expire. Response Schema: `application/json` `id` string required Example: `not_found` A short identifier corresponding to the HTTP status code returned. For example, the ID for a response returning a 404 status code would be "not_found." `message` string required Example: `The resource you were accessing could not be found.` A message providing additional information about the error, including details to help resolve it when possible. `request_id` string optional Example: `4d9d8375-3c56-4925-a3e7-eb137fed17e9` 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 **200** ```json { "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": "alerts@example.com" }, "id": "550e8400-e29b-41d4-a716-446655440000", "name": "On-call email", "updated_at": "2026-09-03T10:15:00Z", "usage": { "rule_count": 2 } } ] } ``` **401** ```json { "id": "unauthorized", "message": "Unable to authenticate you." } ``` **429** ```json { "id": "too_many_requests", "message": "API rate limit exceeded." } ``` **500** ```json { "id": "server_error", "message": "Unexpected server-side error" } ``` **default** ```json { "id": "example_error", "message": "some error message" } ``` * * * ## POST Create a Notification Channel `/v2/insights/notification-channels` 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` ### Payload Content type `application/json` Example ```json { "email": { "to": "alerts@example.com, backup@example.com" }, "name": "On-call email" } ``` ```json { "name": "Platform alerts", "slack": { "channel": "#platform-alerts", "webhook_url": "https://hooks.slack.com/services/T000/B000/XXXXXXXX" } } ``` ```json { "name": "Incident webhook", "webhook": { "bearer_token": { "token": "secret-token" }, "headers": { "X-Custom": "1" }, "signature": { "secret": "whsec" }, "url": "https://example.com/hook" } } ``` ### cURL ```bash 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](https://docs.digitalocean.com/reference/api/reference/index.html.md#rate-limit) for information about how requests expire. `ratelimit-reset` integer The time when the oldest request will expire. The value is given in Unix epoch time. See [https://docs.digitalocean.com/reference/api/reference/#rate-limit](https://docs.digitalocean.com/reference/api/reference/index.html.md#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: `alerts@example.com, backup@example.com` 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](https://docs.digitalocean.com/reference/api/reference/index.html.md#rate-limit) for information about how requests expire. `ratelimit-reset` integer The time when the oldest request will expire. The value is given in Unix epoch time. See [https://docs.digitalocean.com/reference/api/reference/#rate-limit](https://docs.digitalocean.com/reference/api/reference/index.html.md#rate-limit) for information about how requests expire. Response Schema: `application/json` `id` string required Example: `not_found` A short identifier corresponding to the HTTP status code returned. For example, the ID for a response returning a 404 status code would be "not_found." `message` string required Example: `The resource you were accessing could not be found.` A message providing additional information about the error, including details to help resolve it when possible. `request_id` string optional Example: `4d9d8375-3c56-4925-a3e7-eb137fed17e9` 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](https://docs.digitalocean.com/reference/api/reference/index.html.md#rate-limit) for information about how requests expire. `ratelimit-reset` integer The time when the oldest request will expire. The value is given in Unix epoch time. See [https://docs.digitalocean.com/reference/api/reference/#rate-limit](https://docs.digitalocean.com/reference/api/reference/index.html.md#rate-limit) for information about how requests expire. Response Schema: `application/json` `id` string required Example: `not_found` A short identifier corresponding to the HTTP status code returned. For example, the ID for a response returning a 404 status code would be "not_found." `message` string required Example: `The resource you were accessing could not be found.` A message providing additional information about the error, including details to help resolve it when possible. `request_id` string optional Example: `4d9d8375-3c56-4925-a3e7-eb137fed17e9` 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](https://docs.digitalocean.com/reference/api/reference/index.html.md#rate-limit) for information about how requests expire. `ratelimit-reset` integer The time when the oldest request will expire. The value is given in Unix epoch time. See [https://docs.digitalocean.com/reference/api/reference/#rate-limit](https://docs.digitalocean.com/reference/api/reference/index.html.md#rate-limit) for information about how requests expire. Response Schema: `application/json` `id` string required Example: `not_found` A short identifier corresponding to the HTTP status code returned. For example, the ID for a response returning a 404 status code would be "not_found." `message` string required Example: `The resource you were accessing could not be found.` A message providing additional information about the error, including details to help resolve it when possible. `request_id` string optional Example: `4d9d8375-3c56-4925-a3e7-eb137fed17e9` 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](https://docs.digitalocean.com/reference/api/reference/index.html.md#rate-limit) for information about how requests expire. `ratelimit-reset` integer The time when the oldest request will expire. The value is given in Unix epoch time. See [https://docs.digitalocean.com/reference/api/reference/#rate-limit](https://docs.digitalocean.com/reference/api/reference/index.html.md#rate-limit) for information about how requests expire. Response Schema: `application/json` `id` string required Example: `not_found` A short identifier corresponding to the HTTP status code returned. For example, the ID for a response returning a 404 status code would be "not_found." `message` string required Example: `The resource you were accessing could not be found.` A message providing additional information about the error, including details to help resolve it when possible. `request_id` string optional Example: `4d9d8375-3c56-4925-a3e7-eb137fed17e9` 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](https://docs.digitalocean.com/reference/api/reference/index.html.md#rate-limit) for information about how requests expire. `ratelimit-reset` integer The time when the oldest request will expire. The value is given in Unix epoch time. See [https://docs.digitalocean.com/reference/api/reference/#rate-limit](https://docs.digitalocean.com/reference/api/reference/index.html.md#rate-limit) for information about how requests expire. Response Schema: `application/json` `id` string required Example: `not_found` A short identifier corresponding to the HTTP status code returned. For example, the ID for a response returning a 404 status code would be "not_found." `message` string required Example: `The resource you were accessing could not be found.` A message providing additional information about the error, including details to help resolve it when possible. `request_id` string optional Example: `4d9d8375-3c56-4925-a3e7-eb137fed17e9` 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 **201** Example ```json { "notification_channel": { "channel_type": "CHANNEL_TYPE_EMAIL", "created_at": "2026-09-03T10:15:00Z", "email": { "to": "alerts@example.com, backup@example.com" }, "id": "550e8400-e29b-41d4-a716-446655440000", "name": "On-call email", "updated_at": "2026-09-03T10:15:00Z", "usage": { "rule_count": 0 } } } ``` ```json { "notification_channel": { "channel_type": "CHANNEL_TYPE_SLACK", "created_at": "2026-09-03T10:16:00Z", "id": "660e8400-e29b-41d4-a716-446655440001", "name": "Platform alerts", "slack": { "channel": "#platform-alerts", "webhook_url": "********" }, "updated_at": "2026-09-03T10:16:00Z", "usage": { "rule_count": 0 } } } ``` ```json { "notification_channel": { "channel_type": "CHANNEL_TYPE_WEBHOOK", "created_at": "2026-09-03T10:17:00Z", "id": "770e8400-e29b-41d4-a716-446655440002", "name": "Incident webhook", "updated_at": "2026-09-03T10:17:00Z", "usage": { "rule_count": 0 }, "webhook": { "bearer_token": { "token": "********" }, "headers": { "X-Custom": "1" }, "signature": { "secret": "********" }, "url": "https://example.com/hook" } } } ``` **400** ```json { "id": "bad_request", "message": "error parsing request body", "request_id": "4851a473-1621-42ea-b2f9-5071c0ea8414" } ``` **401** ```json { "id": "unauthorized", "message": "Unable to authenticate you." } ``` **429** ```json { "id": "too_many_requests", "message": "API rate limit exceeded." } ``` **500** ```json { "id": "server_error", "message": "Unexpected server-side error" } ``` **default** ```json { "id": "example_error", "message": "some error message" } ``` * * * ## GET Retrieve a Notification Channel `/v2/insights/notification-channels/{id}` 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 ```bash 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](https://docs.digitalocean.com/reference/api/reference/index.html.md#rate-limit) for information about how requests expire. `ratelimit-reset` integer The time when the oldest request will expire. The value is given in Unix epoch time. See [https://docs.digitalocean.com/reference/api/reference/#rate-limit](https://docs.digitalocean.com/reference/api/reference/index.html.md#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: `alerts@example.com, backup@example.com` 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](https://docs.digitalocean.com/reference/api/reference/index.html.md#rate-limit) for information about how requests expire. `ratelimit-reset` integer The time when the oldest request will expire. The value is given in Unix epoch time. See [https://docs.digitalocean.com/reference/api/reference/#rate-limit](https://docs.digitalocean.com/reference/api/reference/index.html.md#rate-limit) for information about how requests expire. Response Schema: `application/json` `id` string required Example: `not_found` A short identifier corresponding to the HTTP status code returned. For example, the ID for a response returning a 404 status code would be "not_found." `message` string required Example: `The resource you were accessing could not be found.` A message providing additional information about the error, including details to help resolve it when possible. `request_id` string optional Example: `4d9d8375-3c56-4925-a3e7-eb137fed17e9` 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](https://docs.digitalocean.com/reference/api/reference/index.html.md#rate-limit) for information about how requests expire. `ratelimit-reset` integer The time when the oldest request will expire. The value is given in Unix epoch time. See [https://docs.digitalocean.com/reference/api/reference/#rate-limit](https://docs.digitalocean.com/reference/api/reference/index.html.md#rate-limit) for information about how requests expire. Response Schema: `application/json` `id` string required Example: `not_found` A short identifier corresponding to the HTTP status code returned. For example, the ID for a response returning a 404 status code would be "not_found." `message` string required Example: `The resource you were accessing could not be found.` A message providing additional information about the error, including details to help resolve it when possible. `request_id` string optional Example: `4d9d8375-3c56-4925-a3e7-eb137fed17e9` 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](https://docs.digitalocean.com/reference/api/reference/index.html.md#rate-limit) for information about how requests expire. `ratelimit-reset` integer The time when the oldest request will expire. The value is given in Unix epoch time. See [https://docs.digitalocean.com/reference/api/reference/#rate-limit](https://docs.digitalocean.com/reference/api/reference/index.html.md#rate-limit) for information about how requests expire. Response Schema: `application/json` `id` string required Example: `not_found` A short identifier corresponding to the HTTP status code returned. For example, the ID for a response returning a 404 status code would be "not_found." `message` string required Example: `The resource you were accessing could not be found.` A message providing additional information about the error, including details to help resolve it when possible. `request_id` string optional Example: `4d9d8375-3c56-4925-a3e7-eb137fed17e9` 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](https://docs.digitalocean.com/reference/api/reference/index.html.md#rate-limit) for information about how requests expire. `ratelimit-reset` integer The time when the oldest request will expire. The value is given in Unix epoch time. See [https://docs.digitalocean.com/reference/api/reference/#rate-limit](https://docs.digitalocean.com/reference/api/reference/index.html.md#rate-limit) for information about how requests expire. Response Schema: `application/json` `id` string required Example: `not_found` A short identifier corresponding to the HTTP status code returned. For example, the ID for a response returning a 404 status code would be "not_found." `message` string required Example: `The resource you were accessing could not be found.` A message providing additional information about the error, including details to help resolve it when possible. `request_id` string optional Example: `4d9d8375-3c56-4925-a3e7-eb137fed17e9` 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](https://docs.digitalocean.com/reference/api/reference/index.html.md#rate-limit) for information about how requests expire. `ratelimit-reset` integer The time when the oldest request will expire. The value is given in Unix epoch time. See [https://docs.digitalocean.com/reference/api/reference/#rate-limit](https://docs.digitalocean.com/reference/api/reference/index.html.md#rate-limit) for information about how requests expire. Response Schema: `application/json` `id` string required Example: `not_found` A short identifier corresponding to the HTTP status code returned. For example, the ID for a response returning a 404 status code would be "not_found." `message` string required Example: `The resource you were accessing could not be found.` A message providing additional information about the error, including details to help resolve it when possible. `request_id` string optional Example: `4d9d8375-3c56-4925-a3e7-eb137fed17e9` 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 **200** Example ```json { "notification_channel": { "channel_type": "CHANNEL_TYPE_EMAIL", "created_at": "2026-09-03T10:15:00Z", "email": { "to": "alerts@example.com, backup@example.com" }, "id": "550e8400-e29b-41d4-a716-446655440000", "name": "On-call email", "updated_at": "2026-09-03T10:15:00Z", "usage": { "rule_count": 0 } } } ``` ```json { "notification_channel": { "channel_type": "CHANNEL_TYPE_SLACK", "created_at": "2026-09-03T10:16:00Z", "id": "660e8400-e29b-41d4-a716-446655440001", "name": "Platform alerts", "slack": { "channel": "#platform-alerts", "webhook_url": "********" }, "updated_at": "2026-09-03T10:16:00Z", "usage": { "rule_count": 0 } } } ``` ```json { "notification_channel": { "channel_type": "CHANNEL_TYPE_WEBHOOK", "created_at": "2026-09-03T10:17:00Z", "id": "770e8400-e29b-41d4-a716-446655440002", "name": "Incident webhook", "updated_at": "2026-09-03T10:17:00Z", "usage": { "rule_count": 0 }, "webhook": { "bearer_token": { "token": "********" }, "headers": { "X-Custom": "1" }, "signature": { "secret": "********" }, "url": "https://example.com/hook" } } } ``` **401** ```json { "id": "unauthorized", "message": "Unable to authenticate you." } ``` **404** ```json { "id": "not_found", "message": "The resource you requested could not be found." } ``` **429** ```json { "id": "too_many_requests", "message": "API rate limit exceeded." } ``` **500** ```json { "id": "server_error", "message": "Unexpected server-side error" } ``` **default** ```json { "id": "example_error", "message": "some error message" } ``` * * * ## PUT Update a Notification Channel `/v2/insights/notification-channels/{id}` 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}` ### Payload Content type `application/json` ```json { "name": "Platform alerts (updated)", "slack": { "channel": "#platform-alerts-prod", "webhook_url": "https://hooks.slack.com/services/T000/B000/NEWTOKEN" } } ``` ### cURL ```bash 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](https://docs.digitalocean.com/reference/api/reference/index.html.md#rate-limit) for information about how requests expire. `ratelimit-reset` integer The time when the oldest request will expire. The value is given in Unix epoch time. See [https://docs.digitalocean.com/reference/api/reference/#rate-limit](https://docs.digitalocean.com/reference/api/reference/index.html.md#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: `alerts@example.com, backup@example.com` 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](https://docs.digitalocean.com/reference/api/reference/index.html.md#rate-limit) for information about how requests expire. `ratelimit-reset` integer The time when the oldest request will expire. The value is given in Unix epoch time. See [https://docs.digitalocean.com/reference/api/reference/#rate-limit](https://docs.digitalocean.com/reference/api/reference/index.html.md#rate-limit) for information about how requests expire. Response Schema: `application/json` `id` string required Example: `not_found` A short identifier corresponding to the HTTP status code returned. For example, the ID for a response returning a 404 status code would be "not_found." `message` string required Example: `The resource you were accessing could not be found.` A message providing additional information about the error, including details to help resolve it when possible. `request_id` string optional Example: `4d9d8375-3c56-4925-a3e7-eb137fed17e9` 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](https://docs.digitalocean.com/reference/api/reference/index.html.md#rate-limit) for information about how requests expire. `ratelimit-reset` integer The time when the oldest request will expire. The value is given in Unix epoch time. See [https://docs.digitalocean.com/reference/api/reference/#rate-limit](https://docs.digitalocean.com/reference/api/reference/index.html.md#rate-limit) for information about how requests expire. Response Schema: `application/json` `id` string required Example: `not_found` A short identifier corresponding to the HTTP status code returned. For example, the ID for a response returning a 404 status code would be "not_found." `message` string required Example: `The resource you were accessing could not be found.` A message providing additional information about the error, including details to help resolve it when possible. `request_id` string optional Example: `4d9d8375-3c56-4925-a3e7-eb137fed17e9` 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](https://docs.digitalocean.com/reference/api/reference/index.html.md#rate-limit) for information about how requests expire. `ratelimit-reset` integer The time when the oldest request will expire. The value is given in Unix epoch time. See [https://docs.digitalocean.com/reference/api/reference/#rate-limit](https://docs.digitalocean.com/reference/api/reference/index.html.md#rate-limit) for information about how requests expire. Response Schema: `application/json` `id` string required Example: `not_found` A short identifier corresponding to the HTTP status code returned. For example, the ID for a response returning a 404 status code would be "not_found." `message` string required Example: `The resource you were accessing could not be found.` A message providing additional information about the error, including details to help resolve it when possible. `request_id` string optional Example: `4d9d8375-3c56-4925-a3e7-eb137fed17e9` 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](https://docs.digitalocean.com/reference/api/reference/index.html.md#rate-limit) for information about how requests expire. `ratelimit-reset` integer The time when the oldest request will expire. The value is given in Unix epoch time. See [https://docs.digitalocean.com/reference/api/reference/#rate-limit](https://docs.digitalocean.com/reference/api/reference/index.html.md#rate-limit) for information about how requests expire. Response Schema: `application/json` `id` string required Example: `not_found` A short identifier corresponding to the HTTP status code returned. For example, the ID for a response returning a 404 status code would be "not_found." `message` string required Example: `The resource you were accessing could not be found.` A message providing additional information about the error, including details to help resolve it when possible. `request_id` string optional Example: `4d9d8375-3c56-4925-a3e7-eb137fed17e9` 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](https://docs.digitalocean.com/reference/api/reference/index.html.md#rate-limit) for information about how requests expire. `ratelimit-reset` integer The time when the oldest request will expire. The value is given in Unix epoch time. See [https://docs.digitalocean.com/reference/api/reference/#rate-limit](https://docs.digitalocean.com/reference/api/reference/index.html.md#rate-limit) for information about how requests expire. Response Schema: `application/json` `id` string required Example: `not_found` A short identifier corresponding to the HTTP status code returned. For example, the ID for a response returning a 404 status code would be "not_found." `message` string required Example: `The resource you were accessing could not be found.` A message providing additional information about the error, including details to help resolve it when possible. `request_id` string optional Example: `4d9d8375-3c56-4925-a3e7-eb137fed17e9` 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](https://docs.digitalocean.com/reference/api/reference/index.html.md#rate-limit) for information about how requests expire. `ratelimit-reset` integer The time when the oldest request will expire. The value is given in Unix epoch time. See [https://docs.digitalocean.com/reference/api/reference/#rate-limit](https://docs.digitalocean.com/reference/api/reference/index.html.md#rate-limit) for information about how requests expire. Response Schema: `application/json` `id` string required Example: `not_found` A short identifier corresponding to the HTTP status code returned. For example, the ID for a response returning a 404 status code would be "not_found." `message` string required Example: `The resource you were accessing could not be found.` A message providing additional information about the error, including details to help resolve it when possible. `request_id` string optional Example: `4d9d8375-3c56-4925-a3e7-eb137fed17e9` 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 **200** Example ```json { "notification_channel": { "channel_type": "CHANNEL_TYPE_EMAIL", "created_at": "2026-09-03T10:15:00Z", "email": { "to": "alerts@example.com, backup@example.com" }, "id": "550e8400-e29b-41d4-a716-446655440000", "name": "On-call email", "updated_at": "2026-09-03T10:15:00Z", "usage": { "rule_count": 0 } } } ``` ```json { "notification_channel": { "channel_type": "CHANNEL_TYPE_SLACK", "created_at": "2026-09-03T10:16:00Z", "id": "660e8400-e29b-41d4-a716-446655440001", "name": "Platform alerts", "slack": { "channel": "#platform-alerts", "webhook_url": "********" }, "updated_at": "2026-09-03T10:16:00Z", "usage": { "rule_count": 0 } } } ``` ```json { "notification_channel": { "channel_type": "CHANNEL_TYPE_WEBHOOK", "created_at": "2026-09-03T10:17:00Z", "id": "770e8400-e29b-41d4-a716-446655440002", "name": "Incident webhook", "updated_at": "2026-09-03T10:17:00Z", "usage": { "rule_count": 0 }, "webhook": { "bearer_token": { "token": "********" }, "headers": { "X-Custom": "1" }, "signature": { "secret": "********" }, "url": "https://example.com/hook" } } } ``` **400** ```json { "id": "bad_request", "message": "error parsing request body", "request_id": "4851a473-1621-42ea-b2f9-5071c0ea8414" } ``` **401** ```json { "id": "unauthorized", "message": "Unable to authenticate you." } ``` **404** ```json { "id": "not_found", "message": "The resource you requested could not be found." } ``` **429** ```json { "id": "too_many_requests", "message": "API rate limit exceeded." } ``` **500** ```json { "id": "server_error", "message": "Unexpected server-side error" } ``` **default** ```json { "id": "example_error", "message": "some error message" } ``` * * * ## DELETE Delete a Notification Channel `/v2/insights/notification-channels/{id}` 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 ```bash 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](https://docs.digitalocean.com/reference/api/reference/index.html.md#rate-limit) for information about how requests expire. `ratelimit-reset` integer The time when the oldest request will expire. The value is given in Unix epoch time. See [https://docs.digitalocean.com/reference/api/reference/#rate-limit](https://docs.digitalocean.com/reference/api/reference/index.html.md#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](https://docs.digitalocean.com/reference/api/reference/index.html.md#rate-limit) for information about how requests expire. `ratelimit-reset` integer The time when the oldest request will expire. The value is given in Unix epoch time. See [https://docs.digitalocean.com/reference/api/reference/#rate-limit](https://docs.digitalocean.com/reference/api/reference/index.html.md#rate-limit) for information about how requests expire. Response Schema: `application/json` `id` string required Example: `not_found` A short identifier corresponding to the HTTP status code returned. For example, the ID for a response returning a 404 status code would be "not_found." `message` string required Example: `The resource you were accessing could not be found.` A message providing additional information about the error, including details to help resolve it when possible. `request_id` string optional Example: `4d9d8375-3c56-4925-a3e7-eb137fed17e9` 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](https://docs.digitalocean.com/reference/api/reference/index.html.md#rate-limit) for information about how requests expire. `ratelimit-reset` integer The time when the oldest request will expire. The value is given in Unix epoch time. See [https://docs.digitalocean.com/reference/api/reference/#rate-limit](https://docs.digitalocean.com/reference/api/reference/index.html.md#rate-limit) for information about how requests expire. Response Schema: `application/json` `id` string required Example: `not_found` A short identifier corresponding to the HTTP status code returned. For example, the ID for a response returning a 404 status code would be "not_found." `message` string required Example: `The resource you were accessing could not be found.` A message providing additional information about the error, including details to help resolve it when possible. `request_id` string optional Example: `4d9d8375-3c56-4925-a3e7-eb137fed17e9` 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](https://docs.digitalocean.com/reference/api/reference/index.html.md#rate-limit) for information about how requests expire. `ratelimit-reset` integer The time when the oldest request will expire. The value is given in Unix epoch time. See [https://docs.digitalocean.com/reference/api/reference/#rate-limit](https://docs.digitalocean.com/reference/api/reference/index.html.md#rate-limit) for information about how requests expire. Response Schema: `application/json` `id` string required Example: `not_found` A short identifier corresponding to the HTTP status code returned. For example, the ID for a response returning a 404 status code would be "not_found." `message` string required Example: `The resource you were accessing could not be found.` A message providing additional information about the error, including details to help resolve it when possible. `request_id` string optional Example: `4d9d8375-3c56-4925-a3e7-eb137fed17e9` 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](https://docs.digitalocean.com/reference/api/reference/index.html.md#rate-limit) for information about how requests expire. `ratelimit-reset` integer The time when the oldest request will expire. The value is given in Unix epoch time. See [https://docs.digitalocean.com/reference/api/reference/#rate-limit](https://docs.digitalocean.com/reference/api/reference/index.html.md#rate-limit) for information about how requests expire. Response Schema: `application/json` `id` string required Example: `not_found` A short identifier corresponding to the HTTP status code returned. For example, the ID for a response returning a 404 status code would be "not_found." `message` string required Example: `The resource you were accessing could not be found.` A message providing additional information about the error, including details to help resolve it when possible. `request_id` string optional Example: `4d9d8375-3c56-4925-a3e7-eb137fed17e9` 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](https://docs.digitalocean.com/reference/api/reference/index.html.md#rate-limit) for information about how requests expire. `ratelimit-reset` integer The time when the oldest request will expire. The value is given in Unix epoch time. See [https://docs.digitalocean.com/reference/api/reference/#rate-limit](https://docs.digitalocean.com/reference/api/reference/index.html.md#rate-limit) for information about how requests expire. Response Schema: `application/json` `id` string required Example: `not_found` A short identifier corresponding to the HTTP status code returned. For example, the ID for a response returning a 404 status code would be "not_found." `message` string required Example: `The resource you were accessing could not be found.` A message providing additional information about the error, including details to help resolve it when possible. `request_id` string optional Example: `4d9d8375-3c56-4925-a3e7-eb137fed17e9` 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](https://docs.digitalocean.com/reference/api/reference/index.html.md#rate-limit) for information about how requests expire. `ratelimit-reset` integer The time when the oldest request will expire. The value is given in Unix epoch time. See [https://docs.digitalocean.com/reference/api/reference/#rate-limit](https://docs.digitalocean.com/reference/api/reference/index.html.md#rate-limit) for information about how requests expire. Response Schema: `application/json` `id` string required Example: `not_found` A short identifier corresponding to the HTTP status code returned. For example, the ID for a response returning a 404 status code would be "not_found." `message` string required Example: `The resource you were accessing could not be found.` A message providing additional information about the error, including details to help resolve it when possible. `request_id` string optional Example: `4d9d8375-3c56-4925-a3e7-eb137fed17e9` 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 **401** ```json { "id": "unauthorized", "message": "Unable to authenticate you." } ``` **404** ```json { "id": "not_found", "message": "The resource you requested could not be found." } ``` **409** ```json { "id": "conflict", "message": "The request could not be completed due to a conflict." } ``` **429** ```json { "id": "too_many_requests", "message": "API rate limit exceeded." } ``` **500** ```json { "id": "server_error", "message": "Unexpected server-side error" } ``` **default** ```json { "id": "example_error", "message": "some error message" } ``` * * * ## GET Execute an instant PromQL query `/v2/insights/query/{region}/prom/api/v1/query` 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 ```bash 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](https://docs.digitalocean.com/reference/api/reference/index.html.md#rate-limit) for information about how requests expire. `ratelimit-reset` integer The time when the oldest request will expire. The value is given in Unix epoch time. See [https://docs.digitalocean.com/reference/api/reference/#rate-limit](https://docs.digitalocean.com/reference/api/reference/index.html.md#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](https://docs.digitalocean.com/reference/api/reference/index.html.md#rate-limit) for information about how requests expire. `ratelimit-reset` integer The time when the oldest request will expire. The value is given in Unix epoch time. See [https://docs.digitalocean.com/reference/api/reference/#rate-limit](https://docs.digitalocean.com/reference/api/reference/index.html.md#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](https://docs.digitalocean.com/reference/api/reference/index.html.md#rate-limit) for information about how requests expire. `ratelimit-reset` integer The time when the oldest request will expire. The value is given in Unix epoch time. See [https://docs.digitalocean.com/reference/api/reference/#rate-limit](https://docs.digitalocean.com/reference/api/reference/index.html.md#rate-limit) for information about how requests expire. Response Schema: `application/json` `id` string required Example: `not_found` A short identifier corresponding to the HTTP status code returned. For example, the ID for a response returning a 404 status code would be "not_found." `message` string required Example: `The resource you were accessing could not be found.` A message providing additional information about the error, including details to help resolve it when possible. `request_id` string optional Example: `4d9d8375-3c56-4925-a3e7-eb137fed17e9` 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](https://docs.digitalocean.com/reference/api/reference/index.html.md#rate-limit) for information about how requests expire. `ratelimit-reset` integer The time when the oldest request will expire. The value is given in Unix epoch time. See [https://docs.digitalocean.com/reference/api/reference/#rate-limit](https://docs.digitalocean.com/reference/api/reference/index.html.md#rate-limit) for information about how requests expire. Response Schema: `application/json` `id` string required Example: `not_found` A short identifier corresponding to the HTTP status code returned. For example, the ID for a response returning a 404 status code would be "not_found." `message` string required Example: `The resource you were accessing could not be found.` A message providing additional information about the error, including details to help resolve it when possible. `request_id` string optional Example: `4d9d8375-3c56-4925-a3e7-eb137fed17e9` 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](https://docs.digitalocean.com/reference/api/reference/index.html.md#rate-limit) for information about how requests expire. `ratelimit-reset` integer The time when the oldest request will expire. The value is given in Unix epoch time. See [https://docs.digitalocean.com/reference/api/reference/#rate-limit](https://docs.digitalocean.com/reference/api/reference/index.html.md#rate-limit) for information about how requests expire. Response Schema: `application/json` `id` string required Example: `not_found` A short identifier corresponding to the HTTP status code returned. For example, the ID for a response returning a 404 status code would be "not_found." `message` string required Example: `The resource you were accessing could not be found.` A message providing additional information about the error, including details to help resolve it when possible. `request_id` string optional Example: `4d9d8375-3c56-4925-a3e7-eb137fed17e9` 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](https://docs.digitalocean.com/reference/api/reference/index.html.md#rate-limit) for information about how requests expire. `ratelimit-reset` integer The time when the oldest request will expire. The value is given in Unix epoch time. See [https://docs.digitalocean.com/reference/api/reference/#rate-limit](https://docs.digitalocean.com/reference/api/reference/index.html.md#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](https://docs.digitalocean.com/reference/api/reference/index.html.md#rate-limit) for information about how requests expire. `ratelimit-reset` integer The time when the oldest request will expire. The value is given in Unix epoch time. See [https://docs.digitalocean.com/reference/api/reference/#rate-limit](https://docs.digitalocean.com/reference/api/reference/index.html.md#rate-limit) for information about how requests expire. Response Schema: `application/json` `id` string required Example: `not_found` A short identifier corresponding to the HTTP status code returned. For example, the ID for a response returning a 404 status code would be "not_found." `message` string required Example: `The resource you were accessing could not be found.` A message providing additional information about the error, including details to help resolve it when possible. `request_id` string optional Example: `4d9d8375-3c56-4925-a3e7-eb137fed17e9` 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](https://docs.digitalocean.com/reference/api/reference/index.html.md#rate-limit) for information about how requests expire. `ratelimit-reset` integer The time when the oldest request will expire. The value is given in Unix epoch time. See [https://docs.digitalocean.com/reference/api/reference/#rate-limit](https://docs.digitalocean.com/reference/api/reference/index.html.md#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](https://docs.digitalocean.com/reference/api/reference/index.html.md#rate-limit) for information about how requests expire. `ratelimit-reset` integer The time when the oldest request will expire. The value is given in Unix epoch time. See [https://docs.digitalocean.com/reference/api/reference/#rate-limit](https://docs.digitalocean.com/reference/api/reference/index.html.md#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](https://docs.digitalocean.com/reference/api/reference/index.html.md#rate-limit) for information about how requests expire. `ratelimit-reset` integer The time when the oldest request will expire. The value is given in Unix epoch time. See [https://docs.digitalocean.com/reference/api/reference/#rate-limit](https://docs.digitalocean.com/reference/api/reference/index.html.md#rate-limit) for information about how requests expire. Response Schema: `application/json` `id` string required Example: `not_found` A short identifier corresponding to the HTTP status code returned. For example, the ID for a response returning a 404 status code would be "not_found." `message` string required Example: `The resource you were accessing could not be found.` A message providing additional information about the error, including details to help resolve it when possible. `request_id` string optional Example: `4d9d8375-3c56-4925-a3e7-eb137fed17e9` 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 **200** ```json { "data": { "result": [ { "metric": { "__name__": "do_droplets_cpu_time" }, "value": [ 1620683817, "1" ] } ], "resultType": "vector" }, "status": "success" } ``` **400** ```json { "error": "missing query parameter", "errorType": "bad_data", "status": "error" } ``` **401** ```json { "id": "unauthorized", "message": "Unable to authenticate you." } ``` **403** ```json { "id": "forbidden", "message": "You do not have permission to perform this action." } ``` **404** ```json { "id": "not_found", "message": "The resource you requested could not be found." } ``` **422** ```json { "error": "missing query parameter", "errorType": "bad_data", "status": "error" } ``` **429** ```json { "id": "too_many_requests", "message": "API rate limit exceeded." } ``` **500** ```json { "error": "missing query parameter", "errorType": "bad_data", "status": "error" } ``` **503** ```json { "error": "missing query parameter", "errorType": "bad_data", "status": "error" } ``` **default** ```json { "id": "example_error", "message": "some error message" } ``` * * * ## GET Execute a range PromQL query `/v2/insights/query/{region}/prom/api/v1/query_range` 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 ```bash 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](https://docs.digitalocean.com/reference/api/reference/index.html.md#rate-limit) for information about how requests expire. `ratelimit-reset` integer The time when the oldest request will expire. The value is given in Unix epoch time. See [https://docs.digitalocean.com/reference/api/reference/#rate-limit](https://docs.digitalocean.com/reference/api/reference/index.html.md#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](https://docs.digitalocean.com/reference/api/reference/index.html.md#rate-limit) for information about how requests expire. `ratelimit-reset` integer The time when the oldest request will expire. The value is given in Unix epoch time. See [https://docs.digitalocean.com/reference/api/reference/#rate-limit](https://docs.digitalocean.com/reference/api/reference/index.html.md#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](https://docs.digitalocean.com/reference/api/reference/index.html.md#rate-limit) for information about how requests expire. `ratelimit-reset` integer The time when the oldest request will expire. The value is given in Unix epoch time. See [https://docs.digitalocean.com/reference/api/reference/#rate-limit](https://docs.digitalocean.com/reference/api/reference/index.html.md#rate-limit) for information about how requests expire. Response Schema: `application/json` `id` string required Example: `not_found` A short identifier corresponding to the HTTP status code returned. For example, the ID for a response returning a 404 status code would be "not_found." `message` string required Example: `The resource you were accessing could not be found.` A message providing additional information about the error, including details to help resolve it when possible. `request_id` string optional Example: `4d9d8375-3c56-4925-a3e7-eb137fed17e9` 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](https://docs.digitalocean.com/reference/api/reference/index.html.md#rate-limit) for information about how requests expire. `ratelimit-reset` integer The time when the oldest request will expire. The value is given in Unix epoch time. See [https://docs.digitalocean.com/reference/api/reference/#rate-limit](https://docs.digitalocean.com/reference/api/reference/index.html.md#rate-limit) for information about how requests expire. Response Schema: `application/json` `id` string required Example: `not_found` A short identifier corresponding to the HTTP status code returned. For example, the ID for a response returning a 404 status code would be "not_found." `message` string required Example: `The resource you were accessing could not be found.` A message providing additional information about the error, including details to help resolve it when possible. `request_id` string optional Example: `4d9d8375-3c56-4925-a3e7-eb137fed17e9` 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](https://docs.digitalocean.com/reference/api/reference/index.html.md#rate-limit) for information about how requests expire. `ratelimit-reset` integer The time when the oldest request will expire. The value is given in Unix epoch time. See [https://docs.digitalocean.com/reference/api/reference/#rate-limit](https://docs.digitalocean.com/reference/api/reference/index.html.md#rate-limit) for information about how requests expire. Response Schema: `application/json` `id` string required Example: `not_found` A short identifier corresponding to the HTTP status code returned. For example, the ID for a response returning a 404 status code would be "not_found." `message` string required Example: `The resource you were accessing could not be found.` A message providing additional information about the error, including details to help resolve it when possible. `request_id` string optional Example: `4d9d8375-3c56-4925-a3e7-eb137fed17e9` 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](https://docs.digitalocean.com/reference/api/reference/index.html.md#rate-limit) for information about how requests expire. `ratelimit-reset` integer The time when the oldest request will expire. The value is given in Unix epoch time. See [https://docs.digitalocean.com/reference/api/reference/#rate-limit](https://docs.digitalocean.com/reference/api/reference/index.html.md#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](https://docs.digitalocean.com/reference/api/reference/index.html.md#rate-limit) for information about how requests expire. `ratelimit-reset` integer The time when the oldest request will expire. The value is given in Unix epoch time. See [https://docs.digitalocean.com/reference/api/reference/#rate-limit](https://docs.digitalocean.com/reference/api/reference/index.html.md#rate-limit) for information about how requests expire. Response Schema: `application/json` `id` string required Example: `not_found` A short identifier corresponding to the HTTP status code returned. For example, the ID for a response returning a 404 status code would be "not_found." `message` string required Example: `The resource you were accessing could not be found.` A message providing additional information about the error, including details to help resolve it when possible. `request_id` string optional Example: `4d9d8375-3c56-4925-a3e7-eb137fed17e9` 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](https://docs.digitalocean.com/reference/api/reference/index.html.md#rate-limit) for information about how requests expire. `ratelimit-reset` integer The time when the oldest request will expire. The value is given in Unix epoch time. See [https://docs.digitalocean.com/reference/api/reference/#rate-limit](https://docs.digitalocean.com/reference/api/reference/index.html.md#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](https://docs.digitalocean.com/reference/api/reference/index.html.md#rate-limit) for information about how requests expire. `ratelimit-reset` integer The time when the oldest request will expire. The value is given in Unix epoch time. See [https://docs.digitalocean.com/reference/api/reference/#rate-limit](https://docs.digitalocean.com/reference/api/reference/index.html.md#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](https://docs.digitalocean.com/reference/api/reference/index.html.md#rate-limit) for information about how requests expire. `ratelimit-reset` integer The time when the oldest request will expire. The value is given in Unix epoch time. See [https://docs.digitalocean.com/reference/api/reference/#rate-limit](https://docs.digitalocean.com/reference/api/reference/index.html.md#rate-limit) for information about how requests expire. Response Schema: `application/json` `id` string required Example: `not_found` A short identifier corresponding to the HTTP status code returned. For example, the ID for a response returning a 404 status code would be "not_found." `message` string required Example: `The resource you were accessing could not be found.` A message providing additional information about the error, including details to help resolve it when possible. `request_id` string optional Example: `4d9d8375-3c56-4925-a3e7-eb137fed17e9` 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 **200** ```json { "data": { "result": [ { "metric": { "__name__": "do_droplets_cpu_time" }, "values": [ [ 1620683817, "1" ], [ 1620683832, "1" ] ] } ], "resultType": "matrix" }, "status": "success" } ``` **400** ```json { "error": "missing query parameter", "errorType": "bad_data", "status": "error" } ``` **401** ```json { "id": "unauthorized", "message": "Unable to authenticate you." } ``` **403** ```json { "id": "forbidden", "message": "You do not have permission to perform this action." } ``` **404** ```json { "id": "not_found", "message": "The resource you requested could not be found." } ``` **422** ```json { "error": "missing query parameter", "errorType": "bad_data", "status": "error" } ``` **429** ```json { "id": "too_many_requests", "message": "API rate limit exceeded." } ``` **500** ```json { "error": "missing query parameter", "errorType": "bad_data", "status": "error" } ``` **503** ```json { "error": "missing query parameter", "errorType": "bad_data", "status": "error" } ``` **default** ```json { "id": "example_error", "message": "some error message" } ``` * * * ## GET List label names `/v2/insights/query/{region}/prom/api/v1/labels` 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 ```bash 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](https://docs.digitalocean.com/reference/api/reference/index.html.md#rate-limit) for information about how requests expire. `ratelimit-reset` integer The time when the oldest request will expire. The value is given in Unix epoch time. See [https://docs.digitalocean.com/reference/api/reference/#rate-limit](https://docs.digitalocean.com/reference/api/reference/index.html.md#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](https://docs.digitalocean.com/reference/api/reference/index.html.md#rate-limit) for information about how requests expire. `ratelimit-reset` integer The time when the oldest request will expire. The value is given in Unix epoch time. See [https://docs.digitalocean.com/reference/api/reference/#rate-limit](https://docs.digitalocean.com/reference/api/reference/index.html.md#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](https://docs.digitalocean.com/reference/api/reference/index.html.md#rate-limit) for information about how requests expire. `ratelimit-reset` integer The time when the oldest request will expire. The value is given in Unix epoch time. See [https://docs.digitalocean.com/reference/api/reference/#rate-limit](https://docs.digitalocean.com/reference/api/reference/index.html.md#rate-limit) for information about how requests expire. Response Schema: `application/json` `id` string required Example: `not_found` A short identifier corresponding to the HTTP status code returned. For example, the ID for a response returning a 404 status code would be "not_found." `message` string required Example: `The resource you were accessing could not be found.` A message providing additional information about the error, including details to help resolve it when possible. `request_id` string optional Example: `4d9d8375-3c56-4925-a3e7-eb137fed17e9` 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](https://docs.digitalocean.com/reference/api/reference/index.html.md#rate-limit) for information about how requests expire. `ratelimit-reset` integer The time when the oldest request will expire. The value is given in Unix epoch time. See [https://docs.digitalocean.com/reference/api/reference/#rate-limit](https://docs.digitalocean.com/reference/api/reference/index.html.md#rate-limit) for information about how requests expire. Response Schema: `application/json` `id` string required Example: `not_found` A short identifier corresponding to the HTTP status code returned. For example, the ID for a response returning a 404 status code would be "not_found." `message` string required Example: `The resource you were accessing could not be found.` A message providing additional information about the error, including details to help resolve it when possible. `request_id` string optional Example: `4d9d8375-3c56-4925-a3e7-eb137fed17e9` 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](https://docs.digitalocean.com/reference/api/reference/index.html.md#rate-limit) for information about how requests expire. `ratelimit-reset` integer The time when the oldest request will expire. The value is given in Unix epoch time. See [https://docs.digitalocean.com/reference/api/reference/#rate-limit](https://docs.digitalocean.com/reference/api/reference/index.html.md#rate-limit) for information about how requests expire. Response Schema: `application/json` `id` string required Example: `not_found` A short identifier corresponding to the HTTP status code returned. For example, the ID for a response returning a 404 status code would be "not_found." `message` string required Example: `The resource you were accessing could not be found.` A message providing additional information about the error, including details to help resolve it when possible. `request_id` string optional Example: `4d9d8375-3c56-4925-a3e7-eb137fed17e9` 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](https://docs.digitalocean.com/reference/api/reference/index.html.md#rate-limit) for information about how requests expire. `ratelimit-reset` integer The time when the oldest request will expire. The value is given in Unix epoch time. See [https://docs.digitalocean.com/reference/api/reference/#rate-limit](https://docs.digitalocean.com/reference/api/reference/index.html.md#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](https://docs.digitalocean.com/reference/api/reference/index.html.md#rate-limit) for information about how requests expire. `ratelimit-reset` integer The time when the oldest request will expire. The value is given in Unix epoch time. See [https://docs.digitalocean.com/reference/api/reference/#rate-limit](https://docs.digitalocean.com/reference/api/reference/index.html.md#rate-limit) for information about how requests expire. Response Schema: `application/json` `id` string required Example: `not_found` A short identifier corresponding to the HTTP status code returned. For example, the ID for a response returning a 404 status code would be "not_found." `message` string required Example: `The resource you were accessing could not be found.` A message providing additional information about the error, including details to help resolve it when possible. `request_id` string optional Example: `4d9d8375-3c56-4925-a3e7-eb137fed17e9` 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](https://docs.digitalocean.com/reference/api/reference/index.html.md#rate-limit) for information about how requests expire. `ratelimit-reset` integer The time when the oldest request will expire. The value is given in Unix epoch time. See [https://docs.digitalocean.com/reference/api/reference/#rate-limit](https://docs.digitalocean.com/reference/api/reference/index.html.md#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](https://docs.digitalocean.com/reference/api/reference/index.html.md#rate-limit) for information about how requests expire. `ratelimit-reset` integer The time when the oldest request will expire. The value is given in Unix epoch time. See [https://docs.digitalocean.com/reference/api/reference/#rate-limit](https://docs.digitalocean.com/reference/api/reference/index.html.md#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](https://docs.digitalocean.com/reference/api/reference/index.html.md#rate-limit) for information about how requests expire. `ratelimit-reset` integer The time when the oldest request will expire. The value is given in Unix epoch time. See [https://docs.digitalocean.com/reference/api/reference/#rate-limit](https://docs.digitalocean.com/reference/api/reference/index.html.md#rate-limit) for information about how requests expire. Response Schema: `application/json` `id` string required Example: `not_found` A short identifier corresponding to the HTTP status code returned. For example, the ID for a response returning a 404 status code would be "not_found." `message` string required Example: `The resource you were accessing could not be found.` A message providing additional information about the error, including details to help resolve it when possible. `request_id` string optional Example: `4d9d8375-3c56-4925-a3e7-eb137fed17e9` 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 **200** ```json { "data": [ "__name__", "job", "instance" ], "status": "success" } ``` **400** ```json { "error": "missing query parameter", "errorType": "bad_data", "status": "error" } ``` **401** ```json { "id": "unauthorized", "message": "Unable to authenticate you." } ``` **403** ```json { "id": "forbidden", "message": "You do not have permission to perform this action." } ``` **404** ```json { "id": "not_found", "message": "The resource you requested could not be found." } ``` **422** ```json { "error": "missing query parameter", "errorType": "bad_data", "status": "error" } ``` **429** ```json { "id": "too_many_requests", "message": "API rate limit exceeded." } ``` **500** ```json { "error": "missing query parameter", "errorType": "bad_data", "status": "error" } ``` **503** ```json { "error": "missing query parameter", "errorType": "bad_data", "status": "error" } ``` **default** ```json { "id": "example_error", "message": "some error message" } ``` * * * ## GET List values for a label `/v2/insights/query/{region}/prom/api/v1/label/{name}/values` 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 ```bash 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](https://docs.digitalocean.com/reference/api/reference/index.html.md#rate-limit) for information about how requests expire. `ratelimit-reset` integer The time when the oldest request will expire. The value is given in Unix epoch time. See [https://docs.digitalocean.com/reference/api/reference/#rate-limit](https://docs.digitalocean.com/reference/api/reference/index.html.md#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](https://docs.digitalocean.com/reference/api/reference/index.html.md#rate-limit) for information about how requests expire. `ratelimit-reset` integer The time when the oldest request will expire. The value is given in Unix epoch time. See [https://docs.digitalocean.com/reference/api/reference/#rate-limit](https://docs.digitalocean.com/reference/api/reference/index.html.md#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](https://docs.digitalocean.com/reference/api/reference/index.html.md#rate-limit) for information about how requests expire. `ratelimit-reset` integer The time when the oldest request will expire. The value is given in Unix epoch time. See [https://docs.digitalocean.com/reference/api/reference/#rate-limit](https://docs.digitalocean.com/reference/api/reference/index.html.md#rate-limit) for information about how requests expire. Response Schema: `application/json` `id` string required Example: `not_found` A short identifier corresponding to the HTTP status code returned. For example, the ID for a response returning a 404 status code would be "not_found." `message` string required Example: `The resource you were accessing could not be found.` A message providing additional information about the error, including details to help resolve it when possible. `request_id` string optional Example: `4d9d8375-3c56-4925-a3e7-eb137fed17e9` 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](https://docs.digitalocean.com/reference/api/reference/index.html.md#rate-limit) for information about how requests expire. `ratelimit-reset` integer The time when the oldest request will expire. The value is given in Unix epoch time. See [https://docs.digitalocean.com/reference/api/reference/#rate-limit](https://docs.digitalocean.com/reference/api/reference/index.html.md#rate-limit) for information about how requests expire. Response Schema: `application/json` `id` string required Example: `not_found` A short identifier corresponding to the HTTP status code returned. For example, the ID for a response returning a 404 status code would be "not_found." `message` string required Example: `The resource you were accessing could not be found.` A message providing additional information about the error, including details to help resolve it when possible. `request_id` string optional Example: `4d9d8375-3c56-4925-a3e7-eb137fed17e9` 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](https://docs.digitalocean.com/reference/api/reference/index.html.md#rate-limit) for information about how requests expire. `ratelimit-reset` integer The time when the oldest request will expire. The value is given in Unix epoch time. See [https://docs.digitalocean.com/reference/api/reference/#rate-limit](https://docs.digitalocean.com/reference/api/reference/index.html.md#rate-limit) for information about how requests expire. Response Schema: `application/json` `id` string required Example: `not_found` A short identifier corresponding to the HTTP status code returned. For example, the ID for a response returning a 404 status code would be "not_found." `message` string required Example: `The resource you were accessing could not be found.` A message providing additional information about the error, including details to help resolve it when possible. `request_id` string optional Example: `4d9d8375-3c56-4925-a3e7-eb137fed17e9` 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](https://docs.digitalocean.com/reference/api/reference/index.html.md#rate-limit) for information about how requests expire. `ratelimit-reset` integer The time when the oldest request will expire. The value is given in Unix epoch time. See [https://docs.digitalocean.com/reference/api/reference/#rate-limit](https://docs.digitalocean.com/reference/api/reference/index.html.md#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](https://docs.digitalocean.com/reference/api/reference/index.html.md#rate-limit) for information about how requests expire. `ratelimit-reset` integer The time when the oldest request will expire. The value is given in Unix epoch time. See [https://docs.digitalocean.com/reference/api/reference/#rate-limit](https://docs.digitalocean.com/reference/api/reference/index.html.md#rate-limit) for information about how requests expire. Response Schema: `application/json` `id` string required Example: `not_found` A short identifier corresponding to the HTTP status code returned. For example, the ID for a response returning a 404 status code would be "not_found." `message` string required Example: `The resource you were accessing could not be found.` A message providing additional information about the error, including details to help resolve it when possible. `request_id` string optional Example: `4d9d8375-3c56-4925-a3e7-eb137fed17e9` 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](https://docs.digitalocean.com/reference/api/reference/index.html.md#rate-limit) for information about how requests expire. `ratelimit-reset` integer The time when the oldest request will expire. The value is given in Unix epoch time. See [https://docs.digitalocean.com/reference/api/reference/#rate-limit](https://docs.digitalocean.com/reference/api/reference/index.html.md#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](https://docs.digitalocean.com/reference/api/reference/index.html.md#rate-limit) for information about how requests expire. `ratelimit-reset` integer The time when the oldest request will expire. The value is given in Unix epoch time. See [https://docs.digitalocean.com/reference/api/reference/#rate-limit](https://docs.digitalocean.com/reference/api/reference/index.html.md#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](https://docs.digitalocean.com/reference/api/reference/index.html.md#rate-limit) for information about how requests expire. `ratelimit-reset` integer The time when the oldest request will expire. The value is given in Unix epoch time. See [https://docs.digitalocean.com/reference/api/reference/#rate-limit](https://docs.digitalocean.com/reference/api/reference/index.html.md#rate-limit) for information about how requests expire. Response Schema: `application/json` `id` string required Example: `not_found` A short identifier corresponding to the HTTP status code returned. For example, the ID for a response returning a 404 status code would be "not_found." `message` string required Example: `The resource you were accessing could not be found.` A message providing additional information about the error, including details to help resolve it when possible. `request_id` string optional Example: `4d9d8375-3c56-4925-a3e7-eb137fed17e9` 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 **200** ```json { "data": [ "do_droplets_cpu_time", "do_droplets_memory_free" ], "status": "success" } ``` **400** ```json { "error": "missing query parameter", "errorType": "bad_data", "status": "error" } ``` **401** ```json { "id": "unauthorized", "message": "Unable to authenticate you." } ``` **403** ```json { "id": "forbidden", "message": "You do not have permission to perform this action." } ``` **404** ```json { "id": "not_found", "message": "The resource you requested could not be found." } ``` **422** ```json { "error": "missing query parameter", "errorType": "bad_data", "status": "error" } ``` **429** ```json { "id": "too_many_requests", "message": "API rate limit exceeded." } ``` **500** ```json { "error": "missing query parameter", "errorType": "bad_data", "status": "error" } ``` **503** ```json { "error": "missing query parameter", "errorType": "bad_data", "status": "error" } ``` **default** ```json { "id": "example_error", "message": "some error message" } ``` * * * ## GET Find series by label selectors `/v2/insights/query/{region}/prom/api/v1/series` 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 ```bash 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](https://docs.digitalocean.com/reference/api/reference/index.html.md#rate-limit) for information about how requests expire. `ratelimit-reset` integer The time when the oldest request will expire. The value is given in Unix epoch time. See [https://docs.digitalocean.com/reference/api/reference/#rate-limit](https://docs.digitalocean.com/reference/api/reference/index.html.md#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](https://docs.digitalocean.com/reference/api/reference/index.html.md#rate-limit) for information about how requests expire. `ratelimit-reset` integer The time when the oldest request will expire. The value is given in Unix epoch time. See [https://docs.digitalocean.com/reference/api/reference/#rate-limit](https://docs.digitalocean.com/reference/api/reference/index.html.md#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](https://docs.digitalocean.com/reference/api/reference/index.html.md#rate-limit) for information about how requests expire. `ratelimit-reset` integer The time when the oldest request will expire. The value is given in Unix epoch time. See [https://docs.digitalocean.com/reference/api/reference/#rate-limit](https://docs.digitalocean.com/reference/api/reference/index.html.md#rate-limit) for information about how requests expire. Response Schema: `application/json` `id` string required Example: `not_found` A short identifier corresponding to the HTTP status code returned. For example, the ID for a response returning a 404 status code would be "not_found." `message` string required Example: `The resource you were accessing could not be found.` A message providing additional information about the error, including details to help resolve it when possible. `request_id` string optional Example: `4d9d8375-3c56-4925-a3e7-eb137fed17e9` 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](https://docs.digitalocean.com/reference/api/reference/index.html.md#rate-limit) for information about how requests expire. `ratelimit-reset` integer The time when the oldest request will expire. The value is given in Unix epoch time. See [https://docs.digitalocean.com/reference/api/reference/#rate-limit](https://docs.digitalocean.com/reference/api/reference/index.html.md#rate-limit) for information about how requests expire. Response Schema: `application/json` `id` string required Example: `not_found` A short identifier corresponding to the HTTP status code returned. For example, the ID for a response returning a 404 status code would be "not_found." `message` string required Example: `The resource you were accessing could not be found.` A message providing additional information about the error, including details to help resolve it when possible. `request_id` string optional Example: `4d9d8375-3c56-4925-a3e7-eb137fed17e9` 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](https://docs.digitalocean.com/reference/api/reference/index.html.md#rate-limit) for information about how requests expire. `ratelimit-reset` integer The time when the oldest request will expire. The value is given in Unix epoch time. See [https://docs.digitalocean.com/reference/api/reference/#rate-limit](https://docs.digitalocean.com/reference/api/reference/index.html.md#rate-limit) for information about how requests expire. Response Schema: `application/json` `id` string required Example: `not_found` A short identifier corresponding to the HTTP status code returned. For example, the ID for a response returning a 404 status code would be "not_found." `message` string required Example: `The resource you were accessing could not be found.` A message providing additional information about the error, including details to help resolve it when possible. `request_id` string optional Example: `4d9d8375-3c56-4925-a3e7-eb137fed17e9` 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](https://docs.digitalocean.com/reference/api/reference/index.html.md#rate-limit) for information about how requests expire. `ratelimit-reset` integer The time when the oldest request will expire. The value is given in Unix epoch time. See [https://docs.digitalocean.com/reference/api/reference/#rate-limit](https://docs.digitalocean.com/reference/api/reference/index.html.md#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](https://docs.digitalocean.com/reference/api/reference/index.html.md#rate-limit) for information about how requests expire. `ratelimit-reset` integer The time when the oldest request will expire. The value is given in Unix epoch time. See [https://docs.digitalocean.com/reference/api/reference/#rate-limit](https://docs.digitalocean.com/reference/api/reference/index.html.md#rate-limit) for information about how requests expire. Response Schema: `application/json` `id` string required Example: `not_found` A short identifier corresponding to the HTTP status code returned. For example, the ID for a response returning a 404 status code would be "not_found." `message` string required Example: `The resource you were accessing could not be found.` A message providing additional information about the error, including details to help resolve it when possible. `request_id` string optional Example: `4d9d8375-3c56-4925-a3e7-eb137fed17e9` 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](https://docs.digitalocean.com/reference/api/reference/index.html.md#rate-limit) for information about how requests expire. `ratelimit-reset` integer The time when the oldest request will expire. The value is given in Unix epoch time. See [https://docs.digitalocean.com/reference/api/reference/#rate-limit](https://docs.digitalocean.com/reference/api/reference/index.html.md#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](https://docs.digitalocean.com/reference/api/reference/index.html.md#rate-limit) for information about how requests expire. `ratelimit-reset` integer The time when the oldest request will expire. The value is given in Unix epoch time. See [https://docs.digitalocean.com/reference/api/reference/#rate-limit](https://docs.digitalocean.com/reference/api/reference/index.html.md#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](https://docs.digitalocean.com/reference/api/reference/index.html.md#rate-limit) for information about how requests expire. `ratelimit-reset` integer The time when the oldest request will expire. The value is given in Unix epoch time. See [https://docs.digitalocean.com/reference/api/reference/#rate-limit](https://docs.digitalocean.com/reference/api/reference/index.html.md#rate-limit) for information about how requests expire. Response Schema: `application/json` `id` string required Example: `not_found` A short identifier corresponding to the HTTP status code returned. For example, the ID for a response returning a 404 status code would be "not_found." `message` string required Example: `The resource you were accessing could not be found.` A message providing additional information about the error, including details to help resolve it when possible. `request_id` string optional Example: `4d9d8375-3c56-4925-a3e7-eb137fed17e9` 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 **200** ```json { "data": [ { "__name__": "do_droplets_cpu_time" } ], "status": "success" } ``` **400** ```json { "error": "missing query parameter", "errorType": "bad_data", "status": "error" } ``` **401** ```json { "id": "unauthorized", "message": "Unable to authenticate you." } ``` **403** ```json { "id": "forbidden", "message": "You do not have permission to perform this action." } ``` **404** ```json { "id": "not_found", "message": "The resource you requested could not be found." } ``` **422** ```json { "error": "missing query parameter", "errorType": "bad_data", "status": "error" } ``` **429** ```json { "id": "too_many_requests", "message": "API rate limit exceeded." } ``` **500** ```json { "error": "missing query parameter", "errorType": "bad_data", "status": "error" } ``` **503** ```json { "error": "missing query parameter", "errorType": "bad_data", "status": "error" } ``` **default** ```json { "id": "example_error", "message": "some error message" } ``` * * * ## POST Search logs `/v2/insights/query/{region}/logs/search` 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](https://github.com/digitalocean/openapi) for details.* `number_value` number optional Example: `42` `string_array_value` object optional *Additional nested properties not shown. Refer to the [full API spec](https://github.com/digitalocean/openapi) 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` ### Payload Content type `application/json` ```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 ```bash 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](https://docs.digitalocean.com/reference/api/reference/index.html.md#rate-limit) for information about how requests expire. `ratelimit-reset` integer The time when the oldest request will expire. The value is given in Unix epoch time. See [https://docs.digitalocean.com/reference/api/reference/#rate-limit](https://docs.digitalocean.com/reference/api/reference/index.html.md#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](https://docs.digitalocean.com/reference/api/reference/index.html.md#rate-limit) for information about how requests expire. `ratelimit-reset` integer The time when the oldest request will expire. The value is given in Unix epoch time. See [https://docs.digitalocean.com/reference/api/reference/#rate-limit](https://docs.digitalocean.com/reference/api/reference/index.html.md#rate-limit) for information about how requests expire. Response Schema: `application/json` `id` string required Example: `not_found` A short identifier corresponding to the HTTP status code returned. For example, the ID for a response returning a 404 status code would be "not_found." `message` string required Example: `The resource you were accessing could not be found.` A message providing additional information about the error, including details to help resolve it when possible. `request_id` string optional Example: `4d9d8375-3c56-4925-a3e7-eb137fed17e9` 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](https://docs.digitalocean.com/reference/api/reference/index.html.md#rate-limit) for information about how requests expire. `ratelimit-reset` integer The time when the oldest request will expire. The value is given in Unix epoch time. See [https://docs.digitalocean.com/reference/api/reference/#rate-limit](https://docs.digitalocean.com/reference/api/reference/index.html.md#rate-limit) for information about how requests expire. Response Schema: `application/json` `id` string required Example: `not_found` A short identifier corresponding to the HTTP status code returned. For example, the ID for a response returning a 404 status code would be "not_found." `message` string required Example: `The resource you were accessing could not be found.` A message providing additional information about the error, including details to help resolve it when possible. `request_id` string optional Example: `4d9d8375-3c56-4925-a3e7-eb137fed17e9` 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](https://docs.digitalocean.com/reference/api/reference/index.html.md#rate-limit) for information about how requests expire. `ratelimit-reset` integer The time when the oldest request will expire. The value is given in Unix epoch time. See [https://docs.digitalocean.com/reference/api/reference/#rate-limit](https://docs.digitalocean.com/reference/api/reference/index.html.md#rate-limit) for information about how requests expire. Response Schema: `application/json` `id` string required Example: `not_found` A short identifier corresponding to the HTTP status code returned. For example, the ID for a response returning a 404 status code would be "not_found." `message` string required Example: `The resource you were accessing could not be found.` A message providing additional information about the error, including details to help resolve it when possible. `request_id` string optional Example: `4d9d8375-3c56-4925-a3e7-eb137fed17e9` 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](https://docs.digitalocean.com/reference/api/reference/index.html.md#rate-limit) for information about how requests expire. `ratelimit-reset` integer The time when the oldest request will expire. The value is given in Unix epoch time. See [https://docs.digitalocean.com/reference/api/reference/#rate-limit](https://docs.digitalocean.com/reference/api/reference/index.html.md#rate-limit) for information about how requests expire. Response Schema: `application/json` `id` string required Example: `not_found` A short identifier corresponding to the HTTP status code returned. For example, the ID for a response returning a 404 status code would be "not_found." `message` string required Example: `The resource you were accessing could not be found.` A message providing additional information about the error, including details to help resolve it when possible. `request_id` string optional Example: `4d9d8375-3c56-4925-a3e7-eb137fed17e9` 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](https://docs.digitalocean.com/reference/api/reference/index.html.md#rate-limit) for information about how requests expire. `ratelimit-reset` integer The time when the oldest request will expire. The value is given in Unix epoch time. See [https://docs.digitalocean.com/reference/api/reference/#rate-limit](https://docs.digitalocean.com/reference/api/reference/index.html.md#rate-limit) for information about how requests expire. Response Schema: `application/json` `id` string required Example: `not_found` A short identifier corresponding to the HTTP status code returned. For example, the ID for a response returning a 404 status code would be "not_found." `message` string required Example: `The resource you were accessing could not be found.` A message providing additional information about the error, including details to help resolve it when possible. `request_id` string optional Example: `4d9d8375-3c56-4925-a3e7-eb137fed17e9` 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](https://docs.digitalocean.com/reference/api/reference/index.html.md#rate-limit) for information about how requests expire. `ratelimit-reset` integer The time when the oldest request will expire. The value is given in Unix epoch time. See [https://docs.digitalocean.com/reference/api/reference/#rate-limit](https://docs.digitalocean.com/reference/api/reference/index.html.md#rate-limit) for information about how requests expire. Response Schema: `application/json` `id` string required Example: `not_found` A short identifier corresponding to the HTTP status code returned. For example, the ID for a response returning a 404 status code would be "not_found." `message` string required Example: `The resource you were accessing could not be found.` A message providing additional information about the error, including details to help resolve it when possible. `request_id` string optional Example: `4d9d8375-3c56-4925-a3e7-eb137fed17e9` 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](https://docs.digitalocean.com/reference/api/reference/index.html.md#rate-limit) for information about how requests expire. `ratelimit-reset` integer The time when the oldest request will expire. The value is given in Unix epoch time. See [https://docs.digitalocean.com/reference/api/reference/#rate-limit](https://docs.digitalocean.com/reference/api/reference/index.html.md#rate-limit) for information about how requests expire. Response Schema: `application/json` `id` string required Example: `not_found` A short identifier corresponding to the HTTP status code returned. For example, the ID for a response returning a 404 status code would be "not_found." `message` string required Example: `The resource you were accessing could not be found.` A message providing additional information about the error, including details to help resolve it when possible. `request_id` string optional Example: `4d9d8375-3c56-4925-a3e7-eb137fed17e9` 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 **200** ```json { "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" } } ``` **400** ```json { "id": "bad_request", "message": "error parsing request body", "request_id": "4851a473-1621-42ea-b2f9-5071c0ea8414" } ``` **401** ```json { "id": "unauthorized", "message": "Unable to authenticate you." } ``` **403** ```json { "id": "forbidden", "message": "You do not have permission to perform this action." } ``` **404** ```json { "id": "not_found", "message": "The resource you requested could not be found." } ``` **429** ```json { "id": "too_many_requests", "message": "API rate limit exceeded." } ``` **500** ```json { "id": "server_error", "message": "Unexpected server-side error" } ``` **default** ```json { "id": "example_error", "message": "some error message" } ``` * * *