DigitalOcean API (unofficial showcase)
GET/v2/insights/alert-instances

List Alert Instances

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.

5 parameters
per_pageintegeroptional
Number of items returned per page
Default:20
pageintegeroptional
Which 'page' of paginated results to return.
Default:1
statusstringoptional
Optional filter. When set, only alert instances with this status are returned.
Allowed:activeresolved
rule_idstringoptional
Optional filter. When set, only alert instances fired by the alert rule with this ID are returned.
resource_urnstringoptional
Optional filter. When set, only resources associated with this resource URN are returned.

6 status codes
200The 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.
alert_instancesarray<object>optional
linksobjectoptional
metaobjectrequired
400There was an error parsing the request body.
idstringrequired
A short identifier corresponding to the HTTP status code returned. For example, the ID for a response returning a 404 status code would be "not_found."
messagestringrequired
A message providing additional information about the error, including details to help resolve it when possible.
request_idstringoptional
Optionally, some endpoints may include a request ID that should be provided when reporting bugs or opening support tickets to help identify the issue.
401Authentication failed due to invalid credentials.
idstringrequired
A short identifier corresponding to the HTTP status code returned. For example, the ID for a response returning a 404 status code would be "not_found."
messagestringrequired
A message providing additional information about the error, including details to help resolve it when possible.
request_idstringoptional
Optionally, some endpoints may include a request ID that should be provided when reporting bugs or opening support tickets to help identify the issue.
429The API rate limit has been exceeded.
idstringrequired
A short identifier corresponding to the HTTP status code returned. For example, the ID for a response returning a 404 status code would be "not_found."
messagestringrequired
A message providing additional information about the error, including details to help resolve it when possible.
request_idstringoptional
Optionally, some endpoints may include a request ID that should be provided when reporting bugs or opening support tickets to help identify the issue.
500There was a server error.
idstringrequired
A short identifier corresponding to the HTTP status code returned. For example, the ID for a response returning a 404 status code would be "not_found."
messagestringrequired
A message providing additional information about the error, including details to help resolve it when possible.
request_idstringoptional
Optionally, some endpoints may include a request ID that should be provided when reporting bugs or opening support tickets to help identify the issue.
defaultThere was an unexpected error.
idstringrequired
A short identifier corresponding to the HTTP status code returned. For example, the ID for a response returning a 404 status code would be "not_found."
messagestringrequired
A message providing additional information about the error, including details to help resolve it when possible.
request_idstringoptional
Optionally, some endpoints may include a request ID that should be provided when reporting bugs or opening support tickets to help identify the issue.

Error handling

A 400 is returned: There was an error parsing the request body. A 401 is returned: Authentication failed due to invalid credentials. A 429 is returned: The API rate limit has been exceeded. A 500 is returned: There was a server error. Any other status is an error: There was an unexpected error.