Give Feedback

godo.Insights.ListAlertInstances()

Generated on 5 Nov 2026 from godo version v1.236.0

Copy page as Markdown View page as Markdown

Usage

client.Insights.ListAlertInstances(ctx context.Context, opt *godo.AlertInstanceListOptions) ([]godo.AlertInstance, *godo.Response, error)

Description

ListAlertInstances lists alert instances, newest trigger first.

This method sends a GET request to /v2/insights/alert-instances.

Parameters

opt *godo.AlertInstanceListOptions

Fields of `godo.AlertInstanceListOptions`

AlertInstanceListOptions are filters for listing alert instances.

Page int
PerPage int
Status string
RuleID string
ResourceURN string

Returns

[]godo.AlertInstance
*godo.Response: The HTTP response, with pagination Links, Meta, and Rate limit information.
error: Non-nil when the request fails. API errors are returned as *godo.ErrorResponse.

Fields of `godo.AlertInstance`

AlertInstance is a read-only firing of an alert rule against a resource.

ID string: JSON key: id
RuleID string: JSON key: rule_id
Severity string: JSON key: severity
Status string: JSON key: status
ResourceURN string: Omitted from JSON when empty. JSON key: resource_urn
Value float64: JSON key: value
TriggeredAt time.Time: JSON key: triggered_at
LastTriggeredAt time.Time: JSON key: last_triggered_at
ResolvedAt *time.Time: Omitted from JSON when empty. JSON key: resolved_at
LastNotifiedAt *time.Time: Omitted from JSON when empty. JSON key: last_notified_at

Request Sample

Show Request Sample

package main

import (
	"context"
	"fmt"
	"log"
	"os"

	"github.com/digitalocean/godo"
)

func main() {
	client := godo.NewFromToken(os.Getenv("DIGITALOCEAN_TOKEN"))
	ctx := context.TODO()

	result, _, err := client.Insights.ListAlertInstances(ctx, &godo.AlertInstanceListOptions{
		Page: 1234567,
		PerPage: 1234567,
		Status: "<your-status>",
		RuleID: "<your-rule-id>",
	})
	if err != nil {
		log.Fatal(err)
	}
	fmt.Printf("%+v\n", result)
}

Pagination

This method returns one page of results. Response.Links carries the pagination state; loop until IsLastPage reports true.

Show Pagination Sample

opt := &godo.ListOptions{Page: 1, PerPage: 50}
for {
	items, resp, err := client.Insights.ListAlertInstances(ctx, opt)
	if err != nil {
		log.Fatal(err)
	}
	fmt.Printf("%+v\n", items)

	if resp.Links == nil || resp.Links.IsLastPage() {
		break
	}
	page, err := resp.Links.CurrentPage()
	if err != nil {
		log.Fatal(err)
	}
	opt.Page = page + 1
}

Response Example

Show Response Example

{
  "alert_instances": [
    {
      "id": "a1b2c3d4-e5f6-7890-abcd-ef1234567890",
      "rule_id": "8f3a2b1c-4d5e-6f7a-8b9c-0d1e2f3a4b5c",
      "severity": "warning",
      "status": "active",
      "resource_urn": "do:droplet:12345",
      "value": 87.5,
      "triggered_at": "2026-09-03T10:15:00Z",
      "last_triggered_at": "2026-09-03T10:45:00Z",
      "last_notified_at": "2026-09-03T10:15:00Z"
    }
  ],
  "links": {
    "pages": {}
  },
  "meta": {
    "total": 1
  }
}