Skip to main content
GET
List
List all alerts for your account. This endpoint supports a number of filters, which can help find alerts matching certain criteria. These filters work similarly to the filters on the incidents endpoint, where a field is specified alongside a comparison operator in the query string. Note that:
  • Filters may be used together, and the result will be alerts that match all filters.
  • All query parameters must be URI encoded.

By deduplication_key

Find all alerts with deduplication_key ABC:

By status

Find all alerts in a firing state:

By alert_source

Find all alerts from a specific alert source (by alert source ID):
Find all alerts not from a specific alert source:

By created_at

Find all alerts that follow specified date parameters for created_at field. Possible values are “gte” (greater than or equal to), “lte” (less than or equal to), and “date_range” (between two dates). The following example finds all alerts created after 2025-01-01:
To find alerts created within a specific date range, use the date_range option with tilde-separated dates:

By updated_at

Find all alerts by when they were last updated. This takes the same “gte”, “lte” and “date_range” operators as created_at. The following example finds all alerts updated since the start of 2025:
This is useful for incremental syncs: instead of re-fetching the full alert history, poll with updated_at[gte] set to the time of your last sync, and page through the results as described below. Two things to keep in mind when syncing this way:
  • updated_at moves whenever we write the alert, which can happen without a visible change to the alert payload. Treat a match as a candidate to re-fetch, not a guaranteed change.
  • Start each sync window a few minutes before your last sync time. Writes can commit out of timestamp order, and the overlap stops those from being missed.

Maintenance windows

By default, all alerts are returned including those held by a maintenance window. To exclude alerts that are held by a maintenance window:

Pagination

The list endpoint is paginated. Every response includes a pagination_meta object, and the field that drives paging is after:
  • page_size — the maximum number of results in this page (defaults to 25, up to 50).
  • after — the cursor for the next page. If after is present there are more results to fetch; if it’s absent, you’ve reached the end.
To page through every result, repeat the request with all filters unchanged and pass the previous response’s after value as the after parameter. Using the largest page_size (50) minimises the number of requests:
Keep repeating until the response no longer contains an after cursor.
An empty alerts array does not mean there are no matching alerts.When filters are applied, an individual page can return an empty alerts array while pagination_meta.after is still present. That means “no matches on this page yet, but there are more results to scan” — it does not mean there are no alerts.Always keep requesting pages until after is absent. Stopping at the first empty page will cause you to miss alerts. Note that total_record_count is not returned for this endpoint, so the presence of after is the only signal that more results remain.

Authorizations

Authorization
string
header
required

API key from your incident.io dashboard (Settings → API keys)

Query Parameters

page_size
integer<int64>
default:25
required

Number of alerts to return per page

Required range: 1 <= x <= 50
Example:

25

after
string

If provided, pass this as the 'after' param to load the next page

Example:

"01FCNDV6P870EA6S7TK1DSYDG0"

deduplication_key
object

Filter on alert deduplication key. The accepted operator is 'is'.

Example:
status
object

Filter on alert status. The accepted operators are 'one_of', or 'not_in'.

Example:
alert_source
object

Filter on alert source by ID. The accepted operators are 'one_of', or 'not_in'.

Example:
alert_group_id
object

Filter on alert group ID. Returns alerts that belong to any of the specified groups. The accepted operator is 'one_of'.

Example:
created_at
object

Filter on alert created at timestamp. Accepted operators are 'gte', 'lte' and 'date_range'.

Example:
updated_at
object

Filter on alert updated at timestamp. Accepted operators are 'gte', 'lte' and 'date_range'.

Example:
attributes
object

Filter on an alerts attributes. Alert attribute ID should be sent, followed by the operator and values. Accepted operator will depend on the attribute type.

Example:
has_notes
object

Filter on whether an alert has notes. The accepted operator is 'is'.

Example:
tags
object

Filter on the tags applied to an alert, by tag name. The accepted operators are 'one_of', 'all_of' and 'not_in'.

Example:
include_maintenance_window
object

Filter on whether to include maintenance window alerts. The accepted operator is 'is'.

Example:

Response

OK response.

alerts
object[]
required
Example:
pagination_meta
object
required
Example: