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:

curl --get 'https://api.incident.io/v2/alerts' \
--data 'deduplication_key[is]=ABC'

By status

Find all alerts in a firing state:

curl --get 'https://api.incident.io/v2/alerts' \
--data 'status[one_of]=firing'

By alert_source

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

curl --get 'https://api.incident.io/v2/alerts' \
--data 'alert_source[one_of]=01GBSQF3FHF7FWZQNWGHAVQ804'

Find all alerts not from a specific alert source:

curl --get 'https://api.incident.io/v2/alerts' \
--data 'alert_source[not_in]=01GBSQF3FHF7FWZQNWGHAVQ804'

By alert_group_id

Find all alerts in a specific alert group:

curl --get 'https://api.incident.io/v2/alerts' \
--data 'alert_group_id[one_of]=01GBSQF3FHF7FWZQNWGHAVQ804'

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:

curl --get 'https://api.incident.io/v2/alerts' \
--data 'created_at[gte]=2025-01-01'

To find alerts created within a specific date range, use the date_range option with tilde-separated dates:

curl --get 'https://api.incident.io/v2/alerts' \
--data 'created_at[date_range]=2024-12-02~2024-12-08'

By has_notes

Find all alerts that have notes attached:

curl --get 'https://api.incident.io/v2/alerts' \
--data 'has_notes[is]=true'

Find all alerts that have no notes attached:

curl --get 'https://api.incident.io/v2/alerts' \
--data 'has_notes[is]=false'

By attributes

Alerts can be filtered by their attribute values. Each filter is keyed by the alert attribute ID, followed by an operator and the values to match. The accepted operators depend on the attribute’s type.

Find all alerts where attribute 01GBSQF3FHF7FWZQNWGHAVQ804 is one of two catalog entries:

curl --get 'https://api.incident.io/v2/alerts' \
--data 'attributes[01GBSQF3FHF7FWZQNWGHAVQ804][one_of]=01GBSQF3FHF7FWZQNWGHAVQ804' \
--data 'attributes[01GBSQF3FHF7FWZQNWGHAVQ804][one_of]=01ET65M7ZARSFZ6TFDFVQDN9AA'

You can filter on multiple attributes at once, and the result will be alerts that match all of them.

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:

curl --get 'https://api.incident.io/v2/alerts' \
--data 'include_maintenance_window[is]=false'

GET

alerts

List

curl --request GET \
  --url https://api.incident.io/v2/alerts \
  --header 'Authorization: Bearer <token>'

const options = {method: 'GET', headers: {Authorization: 'Bearer <token>'}};

fetch('https://api.incident.io/v2/alerts', options)
  .then(res => res.json())
  .then(res => console.log(res))
  .catch(err => console.error(err));

<?php

$curl = curl_init();

curl_setopt_array($curl, [
  CURLOPT_URL => "https://api.incident.io/v2/alerts",
  CURLOPT_RETURNTRANSFER => true,
  CURLOPT_ENCODING => "",
  CURLOPT_MAXREDIRS => 10,
  CURLOPT_TIMEOUT => 30,
  CURLOPT_HTTP_VERSION => CURL_HTTP_VERSION_1_1,
  CURLOPT_CUSTOMREQUEST => "GET",
  CURLOPT_HTTPHEADER => [
    "Authorization: Bearer <token>"
  ],
]);

$response = curl_exec($curl);
$err = curl_error($curl);

curl_close($curl);

if ($err) {
  echo "cURL Error #:" . $err;
} else {
  echo $response;
}

package main

import (
	"fmt"
	"net/http"
	"io"
)

func main() {

	url := "https://api.incident.io/v2/alerts"

	req, _ := http.NewRequest("GET", url, nil)

	req.Header.Add("Authorization", "Bearer <token>")

	res, _ := http.DefaultClient.Do(req)

	defer res.Body.Close()
	body, _ := io.ReadAll(res.Body)

	fmt.Println(string(body))

}

require 'uri'
require 'net/http'

url = URI("https://api.incident.io/v2/alerts")

http = Net::HTTP.new(url.host, url.port)
http.use_ssl = true

request = Net::HTTP::Get.new(url)
request["Authorization"] = 'Bearer <token>'

response = http.request(request)
puts response.read_body

{
  "alerts": [
    {
      "alert_group_ids": [
        "01GW2G3V0S59R238FAHPDS1R66"
      ],
      "alert_source_id": "01GW2G3V0S59R238FAHPDS1R66",
      "attributes": [
        {
          "array_value": [
            {
              "catalog_entry": {
                "catalog_type_id": "01FCNDV6P870EA6S7TK1DSYDG0",
                "id": "01FCNDV6P870EA6S7TK1DSYDG0",
                "name": "Primary On-call"
              },
              "label": "Payments Team",
              "literal": "SEV123"
            }
          ],
          "attribute": {
            "array": false,
            "emoji": "fire",
            "id": "01GW2G3V0S59R238FAHPDS1R66",
            "name": "service",
            "required": false,
            "type": "CatalogEntry[\"01GW2G3V0S59R238FAHPDS1R67\"]"
          },
          "value": {
            "catalog_entry": {
              "catalog_type_id": "01FCNDV6P870EA6S7TK1DSYDG0",
              "id": "01FCNDV6P870EA6S7TK1DSYDG0",
              "name": "Primary On-call"
            },
            "label": "Payments Team",
            "literal": "SEV123"
          }
        }
      ],
      "created_at": "2021-08-17T13:28:57.801578Z",
      "deduplication_key": "4293868629",
      "description": "CPU on the payments service has exceeded 75 percent for 5 minutes",
      "id": "01GW2G3V0S59R238FAHPDS1R66",
      "resolved_at": "2021-08-17T14:28:57.801578Z",
      "source_url": "https://www.my-alerting-platform.com/alerts/my-alert-123",
      "status": "firing",
      "title": "*errors.withMessage: PG::Error failed to connect",
      "updated_at": "2021-08-17T13:28:57.801578Z"
    }
  ],
  "pagination_meta": {
    "after": "01FCNDV6P870EA6S7TK1DSYDG0",
    "page_size": 25
  }
}

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:

curl --get 'https://api.incident.io/v2/alerts' \
--data 'deduplication_key[is]=ABC'

By status

Find all alerts in a firing state:

curl --get 'https://api.incident.io/v2/alerts' \
--data 'status[one_of]=firing'

By alert_source

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

curl --get 'https://api.incident.io/v2/alerts' \
--data 'alert_source[one_of]=01GBSQF3FHF7FWZQNWGHAVQ804'

Find all alerts not from a specific alert source:

curl --get 'https://api.incident.io/v2/alerts' \
--data 'alert_source[not_in]=01GBSQF3FHF7FWZQNWGHAVQ804'

By created_at

curl --get 'https://api.incident.io/v2/alerts' \
--data 'created_at[gte]=2025-01-01'

To find alerts created within a specific date range, use the date_range option with tilde-separated dates:

curl --get 'https://api.incident.io/v2/alerts' \
--data 'created_at[date_range]=2024-12-02~2024-12-08'

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:

curl --get 'https://api.incident.io/v2/alerts' \
--data 'include_maintenance_window[is]=false'

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 250).
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 (250) minimises the number of requests:

# First page
curl --get 'https://api.incident.io/v2/alerts' \
--data 'status[one_of]=firing' \
--data 'page_size=250'

# Next page: pass the `after` cursor returned in the previous response's pagination_meta
curl --get 'https://api.incident.io/v2/alerts' \
--data 'status[one_of]=firing' \
--data 'page_size=250' \
--data 'after=01FCNDV6P870EA6S7TK1DSYDG0'

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'.

Show child attributes

Example:

{ "is": ["01GBSQF3FHF7FWZQNWGHAVQ804"] }

status

object

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

Show child attributes

Example:

{ "one_of": ["firing"] }

alert_source

object

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

Show child attributes

Example:

{ "one_of": ["01GBSQF3FHF7FWZQNWGHAVQ804"] }

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'.

Show child attributes

Example:

{ "one_of": ["01GBSQF3FHF7FWZQNWGHAVQ804"] }

created_at

object

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

Show child attributes

Example:

{ "gte": ["2025-01-01"] }

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.

Show child attributes

Example:

{
  "01GBSQF3FHF7FWZQNWGHAVQ804": {
    "one_of": [
      "01GBSQF3FHF7FWZQNWGHAVQ804",
      "01ET65M7ZARSFZ6TFDFVQDN9AA"
    ]
  }
}

has_notes

object

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

Show child attributes

Example:

{ "is": ["true"] }

include_maintenance_window

object

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

Show child attributes

Example:

{ "is": ["true"] }

Response

200 - application/json

OK response.

alerts

object[]

required

Show child attributes

Example:

[
  {
    "alert_group_ids": ["01GW2G3V0S59R238FAHPDS1R66"],
    "alert_source_id": "01GW2G3V0S59R238FAHPDS1R66",
    "attributes": [
      {
        "array_value": [
          {
            "catalog_entry": {
              "catalog_type_id": "01FCNDV6P870EA6S7TK1DSYDG0",
              "id": "01FCNDV6P870EA6S7TK1DSYDG0",
              "name": "Primary On-call"
            },
            "label": "Payments Team",
            "literal": "SEV123"
          }
        ],
        "attribute": {
          "array": false,
          "emoji": "fire",
          "id": "01GW2G3V0S59R238FAHPDS1R66",
          "name": "service",
          "required": false,
          "type": "CatalogEntry[\"01GW2G3V0S59R238FAHPDS1R67\"]"
        },
        "value": {
          "catalog_entry": {
            "catalog_type_id": "01FCNDV6P870EA6S7TK1DSYDG0",
            "id": "01FCNDV6P870EA6S7TK1DSYDG0",
            "name": "Primary On-call"
          },
          "label": "Payments Team",
          "literal": "SEV123"
        }
      }
    ],
    "created_at": "2021-08-17T13:28:57.801578Z",
    "deduplication_key": "4293868629",
    "description": "CPU on the payments service has exceeded 75 percent for 5 minutes",
    "id": "01GW2G3V0S59R238FAHPDS1R66",
    "resolved_at": "2021-08-17T14:28:57.801578Z",
    "source_url": "https://www.my-alerting-platform.com/alerts/my-alert-123",
    "status": "firing",
    "title": "*errors.withMessage: PG::Error failed to connect",
    "updated_at": "2021-08-17T13:28:57.801578Z"
  }
]

pagination_meta

object

required

Show child attributes

Example:

{
  "after": "01FCNDV6P870EA6S7TK1DSYDG0",
  "page_size": 25
}

⌘I

List

curl --request GET \
  --url https://api.incident.io/v2/alerts \
  --header 'Authorization: Bearer <token>'

const options = {method: 'GET', headers: {Authorization: 'Bearer <token>'}};

fetch('https://api.incident.io/v2/alerts', options)
  .then(res => res.json())
  .then(res => console.log(res))
  .catch(err => console.error(err));

<?php

$curl = curl_init();

curl_setopt_array($curl, [
  CURLOPT_URL => "https://api.incident.io/v2/alerts",
  CURLOPT_RETURNTRANSFER => true,
  CURLOPT_ENCODING => "",
  CURLOPT_MAXREDIRS => 10,
  CURLOPT_TIMEOUT => 30,
  CURLOPT_HTTP_VERSION => CURL_HTTP_VERSION_1_1,
  CURLOPT_CUSTOMREQUEST => "GET",
  CURLOPT_HTTPHEADER => [
    "Authorization: Bearer <token>"
  ],
]);

$response = curl_exec($curl);
$err = curl_error($curl);

curl_close($curl);

if ($err) {
  echo "cURL Error #:" . $err;
} else {
  echo $response;
}

package main

import (
	"fmt"
	"net/http"
	"io"
)

func main() {

	url := "https://api.incident.io/v2/alerts"

	req, _ := http.NewRequest("GET", url, nil)

	req.Header.Add("Authorization", "Bearer <token>")

	res, _ := http.DefaultClient.Do(req)

	defer res.Body.Close()
	body, _ := io.ReadAll(res.Body)

	fmt.Println(string(body))

}

require 'uri'
require 'net/http'

url = URI("https://api.incident.io/v2/alerts")

http = Net::HTTP.new(url.host, url.port)
http.use_ssl = true

request = Net::HTTP::Get.new(url)
request["Authorization"] = 'Bearer <token>'

response = http.request(request)
puts response.read_body

{
  "alerts": [
    {
      "alert_group_ids": [
        "01GW2G3V0S59R238FAHPDS1R66"
      ],
      "alert_source_id": "01GW2G3V0S59R238FAHPDS1R66",
      "attributes": [
        {
          "array_value": [
            {
              "catalog_entry": {
                "catalog_type_id": "01FCNDV6P870EA6S7TK1DSYDG0",
                "id": "01FCNDV6P870EA6S7TK1DSYDG0",
                "name": "Primary On-call"
              },
              "label": "Payments Team",
              "literal": "SEV123"
            }
          ],
          "attribute": {
            "array": false,
            "emoji": "fire",
            "id": "01GW2G3V0S59R238FAHPDS1R66",
            "name": "service",
            "required": false,
            "type": "CatalogEntry[\"01GW2G3V0S59R238FAHPDS1R67\"]"
          },
          "value": {
            "catalog_entry": {
              "catalog_type_id": "01FCNDV6P870EA6S7TK1DSYDG0",
              "id": "01FCNDV6P870EA6S7TK1DSYDG0",
              "name": "Primary On-call"
            },
            "label": "Payments Team",
            "literal": "SEV123"
          }
        }
      ],
      "created_at": "2021-08-17T13:28:57.801578Z",
      "deduplication_key": "4293868629",
      "description": "CPU on the payments service has exceeded 75 percent for 5 minutes",
      "id": "01GW2G3V0S59R238FAHPDS1R66",
      "resolved_at": "2021-08-17T14:28:57.801578Z",
      "source_url": "https://www.my-alerting-platform.com/alerts/my-alert-123",
      "status": "firing",
      "title": "*errors.withMessage: PG::Error failed to connect",
      "updated_at": "2021-08-17T13:28:57.801578Z"
    }
  ],
  "pagination_meta": {
    "after": "01FCNDV6P870EA6S7TK1DSYDG0",
    "page_size": 25
  }
}

Getting started

Webhooks

Audit logs

Deprecated endpoints

List

By deduplication_key

By status

By alert_source

By alert_group_id

By created_at

By has_notes

By attributes

Maintenance windows

By deduplication_key

By status

By alert_source

By created_at

Maintenance windows

Authorizations

Query Parameters

Response

​By deduplication_key

​By status

​By alert_source

​By created_at

​Maintenance windows

​Pagination

Authorizations

Query Parameters

Response

By deduplication_key

By status

By alert_source

By created_at

Maintenance windows

Pagination