> Documentation index for AI agents: https://docs.pagerduty.com/llms.txt

# List alert grouping settings

`GET https://api.pagerduty.com/alert_grouping_settings`

List all of your alert grouping settings including both single service settings and global content based settings.

The settings part of Alert Grouper service allows us to create Alert Grouping Settings and configs that are required to be used during grouping of the alerts.

Scoped OAuth requires: `services.read`

## Authorization

- **api_key** (apiKey) — `Authorization` header. The API Key with format `Token token=<API_KEY>`

## Query parameters

| Name | Type | Required | Description |
|---|---|---|---|
| `after` | string |  | Cursor to retrieve next page; only present if next page exists. |
| `before` | string |  | Cursor to retrieve previous page; only present if not on first page. |
| `total` | boolean |  | By default the `total` field in pagination responses is set to `null` to provide the fastest possible response times. Set `total` to `true` for this field to be populated. See our [Pagination Docs](https://docs.pagerduty.com/developer/pagination) for more information. Default: `false`. |
| `limit` | integer |  | The number of results per page. |
| `service_ids[]` | array of string |  | An array of service IDs. Only results related to these services will be returned. |

## Header parameters

| Name | Type | Required | Description |
|---|---|---|---|
| `Accept` | string | yes | The `Accept` header is used as a versioning header. Default: `application/vnd.pagerduty+json;version=2`. |

## Response 200

An array of alert grouping settings.

### `application/json`

| Field | Type | Required | Description |
|---|---|---|---|
| `alert_grouping_settings` | array of object | yes | The list of alert grouping settings your account has. |
| `alert_grouping_settings[].id` | string |  | Read-only. |
| `alert_grouping_settings[].name` | string \| null |  | An optional short-form string that provides succinct information about an AlertGroupingSetting object suitable for primary labeling of the entity. It is not intended to be an identifier. |
| `alert_grouping_settings[].description` | string \| null |  | An optional description in string that provides more information about an AlertGroupingSetting object. |
| `alert_grouping_settings[].type` | string |  | One of: `content_based`, `content_based_intelligent`, `intelligent`, `time`. |
| `alert_grouping_settings[].config` | one of: object \| object \| object \| object |  |  |
| `alert_grouping_settings[].config.aggregate` | string |  | (Content Only Grouping) Whether Alerts should be grouped if `all` or `any` specified fields match. If `all` is selected, an exact match on every specified field name must occur for Alerts to be grouped. If `any` is selected, Alerts will be grouped when there is an exact match on at least one of the specified fields. One of: `all, any`. |
| `alert_grouping_settings[].config.fields` | array of string |  | (Content Only Grouping) An array of strings which represent the fields with which to group against. Depending on the aggregate, Alerts will group if some or all the fields match. |
| `alert_grouping_settings[].config.time_window` | integer |  | (Content Only Grouping) The maximum amount of time allowed between Alerts. Any Alerts arriving greater than `time_window` seconds apart will not be grouped together. This is a rolling time window up to 24 hours and is counted from the most recently grouped alert. The window is extended every time a new alert is added to the group, up to 24 hours (24 hours only applies to single-service settings). To use the "recommended_time_window," set the value to 0, otherwise the value must be between 300 <= time_window <= 3600 or 86400(i.e. 24 hours). Minimum: 300. Maximum: 86400. |
| `alert_grouping_settings[].config.recommended_time_window` | integer |  | (Content Only Grouping) In order to ensure your Service has the optimal grouping window, we use data science to calculate your Service's average Alert inter-arrival time. We encourage customers to use this value. Please set `time_window` to 0 to use the `recommended_time_window`. Read-only. |
| `alert_grouping_settings[].config.aggregate` | string |  | (Content and Intelligent Grouping) Whether Alerts should be grouped if `all` or `any` specified fields match. If `all` is selected, an exact match on every specified field name must occur for Alerts to be grouped. If `any` is selected, Alerts will be grouped when there is an exact match on at least one of the specified fields. One of: `all, any`. |
| `alert_grouping_settings[].config.fields` | array of string |  | (Content and Intelligent Grouping) An array of strings which represent the fields with which to group against. Depending on the aggregate, Alerts will group if some or all the fields match. |
| `alert_grouping_settings[].config.time_window` | integer |  | (Content and Intelligent Grouping) The maximum amount of time allowed between Alerts. Any Alerts arriving greater than `time_window` seconds apart will not be grouped together. This is a rolling time window up to 24 hours and is counted from the most recently grouped alert. The window is extended every time a new alert is added to the group, up to 24 hours (24 hours only applies to single-service settings). To use the "recommended_time_window," set the value to 0, otherwise the value must be between 300 <= time_window <= 3600. Minimum: 300. Maximum: 3600. |
| `alert_grouping_settings[].config.recommended_time_window` | integer |  | (Content and Intelligent Grouping) In order to ensure your Service has the optimal grouping window, we use data science to calculate your Service's average Alert inter-arrival time. We encourage customers to use this value. Please set `time_window` to 0 to use the `recommended_time_window`. Read-only. |
| `alert_grouping_settings[].config.timeout` | integer |  | (Time Grouping) The duration in seconds within which to automatically group incoming Alerts. To continue grouping Alerts until the Incident is resolved, set this value to 0. Minimum: 60. Maximum: 86400. |
| `alert_grouping_settings[].config.time_window` | integer |  | (Intelligent Grouping) The maximum amount of time allowed between Alerts. Any Alerts arriving greater than `time_window` seconds apart will not be grouped together. This is a rolling time window up to 24 hours and is counted from the most recently grouped alert. The window is extended every time a new alert is added to the group, up to 24 hours (24 hours only applies to single-service settings). To use the "recommended_time_window," set the value to 0, otherwise the value must be between 300 <= time_window <= 3600. Minimum: 300. Maximum: 3600. |
| `alert_grouping_settings[].config.recommended_time_window` | integer |  | (Intelligent Grouping) In order to ensure your Service has the optimal grouping window, we use data science to calculate your Service's average Alert inter-arrival time. We encourage customers to use this value. Please set `time_window` to 0 to use the `recommended_time_window`. Read-only. |
| `alert_grouping_settings[].config.iag_fields` | array of string |  | (Intelligent Grouping) An array of strings which represent the iag fields with which to intelligently group against. Default: `["summary"]`. |
| `alert_grouping_settings[].services` | array of object |  | The array of one or many Services with just ServiceID/name that the AlertGroupingSetting applies to. Type of content_based_intelligent allows for only one service in the array. |
| `alert_grouping_settings[].services[].id` | string | yes | Read-only. |
| `alert_grouping_settings[].services[].summary` | string \| null |  | A short-form, server-generated string that provides succinct, important information about an object suitable for primary labeling of an entity in a client. In many cases, this will be identical to `name`, though it is not intended to be an identifier. Read-only. |
| `alert_grouping_settings[].services[].type` | string | yes | One of: `service_reference`. |
| `alert_grouping_settings[].services[].self` | string \| null (url) |  | the API show URL at which the object is accessible. Read-only. |
| `alert_grouping_settings[].services[].html_url` | string \| null (url) |  | a URL at which the entity is uniquely displayed in the Web app. Read-only. |
| `alert_grouping_settings[].created_at` | string (date-time) |  | The ISO8601 date/time an AlertGroupingSetting got created at. Read-only. |
| `alert_grouping_settings[].updated_at` | string (date-time) |  | The ISO8601 date/time an AlertGroupingSetting last got updated at. Read-only. |

Example: Response Example

```json
{
  "alert_grouping_settings": [
    {
      "id": "PJWA06X",
      "name": "Example of Alert Grouping Setting",
      "description": "This is an example of list of Alert Grouping Settings",
      "type": "content_based",
      "config": {
        "time_window": 86400,
        "aggregate": "all",
        "fields": [
          "summary",
          "component",
          "custom_details.host",
          "custom_details.field1.field2"
        ]
      },
      "services": [
        {
          "id": "P0KJZ0A",
          "name": "Payment Service"
        },
        {
          "id": "PA15YRT",
          "name": "Checkout Service"
        }
      ],
      "created_at": "2022-12-13T19:55:01.171Z",
      "updated_at": "2023-08-24T18:29:35.630Z"
    }
  ],
  "after": "g3QAAAACZAACaWRhB2QAC2luc2VydGVkX2F0dAAAAAlkAApfX3N0cnVjdF9fZAAURWxpeGlyLk5haXZlRGF0ZVRpbWVkAAhjYWxlbmRhcmQAE0VsaXhpci5DYWxlbmRhci5JU09kAANkYXlhA2QABGhvdXJhFGQAC21pY3Jvc2Vjb25kaAJiAAL81WEGZAAGbWludXRlYR5kAAVtb250aGEIZAAGc2Vjb25kYR5kAAR5ZWFyYgAAB",
  "before": "g3QAAAACZAACaWRhCGQAC2luc2VydGVkX2F0dAAAAAlkAApfX3N0cnVjdF9fZAAURWxpeGlyLk5haXZlRGF0ZVRpbWVkAAhjYWxlbmRhcmQAE0VsaXhpci5DYWxlbmRhci5JU09kAANkYXlhA2QABGhvdXJhFGQAC21pY3Jvc2Vjb25kaAJiAANYzWEGZAAGbWludXRlYR5kAAVtb250aGEIZAAGc2Vjb25kYR5kAAR5ZWFyYgAAB",
  "limit": 25,
  "total": null
}
```

## Response 401

Caller did not supply credentials or did not provide the correct credentials.
If you are using an API key, it may be invalid or your Authorization header may be malformed.

### `application/json`

| Field | Type | Required | Description |
|---|---|---|---|
| `error` | object |  |  |
| `error.code` | integer |  | Read-only. |
| `error.message` | string |  | Error message string. Read-only. |
| `error.errors` | array of string |  | Read-only. |

## Developer Agreement

Your access to and use of the PagerDuty Developer Services is governed by the [PagerDuty Developer Agreement](https://docs.pagerduty.com/developer/pagerduty-developer-agreement).