PagerDuty Alert Grouping Settings API
Alert Grouping Settings allow you to configure how alerts in services are grouped together into incidents.
Work with this as data
Every API here is available over the APIs.io API and to AI agents over MCP.
MCP server
One button, every client — Claude, Cursor, VS Code and the rest.
https://apis.io/mcp
Tools for apis
7 MCP tools reach this
find_apisBrowse and filter every API in the catalog.get_api_artifactsOne API's artifacts, grouped by type.get_openapiThe primary OpenAPI for this API.find_similar_apisAPIs that look like this one.apis_io_searchSTART HERE — APIs, providers and tags for one query, each with its total.resolveTurn a domain, URL or GitHub org into the provider it belongs to.find_cohortsEvery scored population of providers in the catalog.
Call it yourself
curl for this page
This API
curl "https://apis.io/api/v1/apis/pagerduty-alert-grouping-settings-api"
All apis
curl "https://apis.io/api/v1/apis?limit=25"Discovery needs no key. Ratings and market analysis are Pro.
Get an API key
Free tier, no form to fill in. Signing in shares your email address with us — we store it to create your key and to recognise you if you sign in with another provider. See our Privacy Policy and Terms.
A second provider on the same verified email joins the account you already have.
OpenAPI Specification
openapi: 3.2.0
info:
description: 'This document describes the PagerDuty REST APIs.
For guides and examples please visit our Documentation.
Our REST APIs are defined in OpenAPI v3.x. You can view the schema at github.com/PagerDuty/api-schema.
Note that properties in some schemas have fields not shown by default such as `readOnly`, `format`, and `default`. Hover your cursor over the right column that looks like `optional+1` to see the full list of fields.'
contact:
name: PagerDuty Support
url: http://www.pagerduty.com/support
email: support@pagerduty.com
title: PagerDuty Alert Grouping Settings API
version: 2.0.0
servers:
- url: https://api.pagerduty.com
description: PagerDuty V2 API.
security:
- api_key: []
tags:
- name: Alert Grouping Settings
description: Alert Grouping Settings allow you to configure how alerts in services are grouped together into incidents.
paths:
/alert_grouping_settings:
description: List
get:
x-pd-requires-scope: services.read
tags:
- Alert Grouping Settings
operationId: listAlertGroupingSettings
description: '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`'
summary: PagerDuty List alert grouping settings
parameters:
- $ref: '#/components/parameters/header_Accept'
- $ref: '#/components/parameters/header_Content-Type'
- $ref: '#/components/parameters/offset_after'
- $ref: '#/components/parameters/offset_before'
- $ref: '#/components/parameters/offset_total'
- $ref: '#/components/parameters/offset_limit'
- $ref: '#/components/parameters/services'
responses:
'200':
description: An array of alert grouping settings.
content:
application/json:
schema:
allOf:
- type: object
properties:
alert_grouping_settings:
type: array
description: The list of alert grouping settings your account has.
items:
$ref: '#/components/schemas/AlertGroupingSetting'
required:
- alert_grouping_settings
examples:
response:
summary: Response Example
value:
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
'401':
$ref: '#/components/responses/Unauthorized'
post:
x-pd-requires-scope: services.write
tags:
- Alert Grouping Settings
operationId: postAlertGroupingSettings
description: 'Create a new Alert Grouping Setting.
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.
This endpoint will be used to create an instance of AlertGroupingSettings for either one service or many services that are in the alert group setting.
Scoped OAuth requires: `services.write`'
summary: PagerDuty Create an Alert Grouping Setting
parameters:
- $ref: '#/components/parameters/header_Accept'
- $ref: '#/components/parameters/header_Content-Type'
requestBody:
content:
application/json:
schema:
type: object
properties:
alert_grouping_setting:
$ref: '#/components/schemas/AlertGroupingSetting'
required:
- alert_grouping_setting
examples:
request:
summary: Request Example
value:
alert_grouping_setting:
id: PZC4OM1
name: Example of Alert Grouping Setting
description: This Alert Grouping Setting is an example
type: content_based
config:
time_window: 900
aggregate: all
fields:
- summary
- component
- custom_details.host
- custom_details.field1.field2
services:
- id: P0KJZ0A
- id: PA15YRT
responses:
'201':
description: The new Alert Grouping Setting.
content:
application/json:
schema:
type: object
properties:
alert_grouping_setting:
$ref: '#/components/schemas/AlertGroupingSetting'
required:
- alert_grouping_setting
examples:
response:
summary: Response Example
value:
alert_grouping_setting:
id: PZC4OM1
name: Example of Alert Grouping Setting
description: This Alert Grouping Setting is an example
type: content_based
config:
time_window: 900
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'
'400':
$ref: '#/components/responses/ArgumentError'
'401':
$ref: '#/components/responses/Unauthorized'
'403':
$ref: '#/components/responses/Forbidden'
/alert_grouping_settings/{id}:
description: Retrieve, modify, or delete Alert Grouping Settings
get:
x-pd-requires-scope: services.read
tags:
- Alert Grouping Settings
operationId: getAlertGroupingSetting
description: 'Get an existing Alert Grouping Setting.
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`'
summary: PagerDuty Get an Alert Grouping Setting
parameters:
- $ref: '#/components/parameters/header_Accept'
- $ref: '#/components/parameters/header_Content-Type'
- $ref: '#/components/parameters/id'
responses:
'200':
description: The Alert Grouping Setting.
content:
application/json:
schema:
type: object
properties:
alert_grouping_setting:
$ref: '#/components/schemas/AlertGroupingSetting'
required:
- alert_grouping_setting
examples:
response:
summary: Response Example
value:
alert_grouping_setting:
id: PZC4OM1
name: Example of Alert Grouping Setting
description: This Alert Grouping Setting is an example
type: content_based
config:
time_window: 900
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'
'401':
$ref: '#/components/responses/Unauthorized'
'404':
$ref: '#/components/responses/NotFound'
delete:
x-pd-requires-scope: services.write
tags:
- Alert Grouping Settings
operationId: deleteAlertGroupingSetting
description: 'Delete an existing Alert Grouping Setting.
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.write`'
summary: PagerDuty Delete an Alert Grouping Setting
parameters:
- $ref: '#/components/parameters/header_Accept'
- $ref: '#/components/parameters/header_Content-Type'
- $ref: '#/components/parameters/id'
responses:
'204':
description: The Alert Grouping Setting was deleted successfully.
'401':
$ref: '#/components/responses/Unauthorized'
'404':
$ref: '#/components/responses/NotFound'
put:
x-pd-requires-scope: services.write
tags:
- Alert Grouping Settings
operationId: putAlertGroupingSetting
description: 'Update an Alert Grouping Setting.
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.
if `services` are not provided in the request, then the existing services will not be removed from the setting.
Scoped OAuth requires: `services.write`'
summary: PagerDuty Update an Alert Grouping Setting
parameters:
- $ref: '#/components/parameters/header_Accept'
- $ref: '#/components/parameters/header_Content-Type'
- $ref: '#/components/parameters/id'
requestBody:
content:
application/json:
schema:
type: object
properties:
alert_grouping_setting:
$ref: '#/components/schemas/AlertGroupingSetting'
required:
- alert_grouping_setting
examples:
request:
summary: Request Example
value:
alert_grouping_setting:
id: PZC4OM1
name: Example of Alert Grouping Setting
description: This Alert Grouping Setting is an example
type: content_based
config:
time_window: 900
aggregate: all
fields:
- summary
- component
- custom_details.host
- custom_details.field1.field2
services:
- id: P0KJZ0A
- id: PA15YRT
responses:
'200':
description: The updated Alert Grouping Setting.
content:
application/json:
schema:
type: object
properties:
alert_grouping_setting:
$ref: '#/components/schemas/AlertGroupingSetting'
required:
- alert_grouping_setting
examples:
response:
summary: Response Example
value:
alert_grouping_setting:
id: PZC4OM1
name: Example of Alert Grouping Setting
description: This Alert Grouping Setting is an example
type: content_based
config:
time_window: 900
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'
'400':
$ref: '#/components/responses/ArgumentError'
'401':
$ref: '#/components/responses/Unauthorized'
'404':
$ref: '#/components/responses/NotFound'
components:
schemas:
ServiceReference:
allOf:
- $ref: '#/components/schemas/Reference'
- type: object
properties:
type:
type: string
enum:
- service_reference
AlertGroupingSetting:
type: object
description: 'Defines how alerts will be automatically grouped into incidents based on the configurations defined. Note that the Alert Grouping Setting features are available only on certain plans.
'
properties:
id:
type: string
readOnly: true
name:
type:
- string
- 'null'
description: 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.
description:
type:
- string
- 'null'
description: An optional description in string that provides more information about an AlertGroupingSetting object.
type:
type: string
enum:
- content_based
- content_based_intelligent
config:
anyOf:
- $ref: '#/components/schemas/ContentBasedAlertGroupingConfiguration'
- $ref: '#/components/schemas/ContentBasedIntelligentAlertGroupingConfiguration'
services:
type: array
description: 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.
items:
$ref: '#/components/schemas/ServiceReference'
created_at:
type: string
format: date-time
description: The ISO8601 date/time an AlertGroupingSetting got created at.
readOnly: true
updated_at:
type: string
format: date-time
description: The ISO8601 date/time an AlertGroupingSetting last got updated at.
readOnly: true
ContentBasedAlertGroupingConfiguration:
type: object
title: Content Only Grouping
description: The configuration for Content Based Alert Grouping
properties:
aggregate:
type: string
description: 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.
enum:
- all, any
fields:
type: array
description: 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.
time_window:
type: integer
minimum: 300
maximum: 86400
description: 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).
recommended_time_window:
readOnly: true
type: integer
description: 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 customer`s to use this value, please set `time_window` to 0 to use the `recommended_time_window`.
ContentBasedIntelligentAlertGroupingConfiguration:
type: object
title: Content and Intelligent Grouping
description: The configuration for Content Based Intelligent Alert Grouping
properties:
aggregate:
type: string
description: 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.
enum:
- all, any
fields:
type: array
description: 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.
time_window:
type: integer
minimum: 300
maximum: 3600
description: 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.
recommended_time_window:
readOnly: true
type: integer
description: 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 customer`s to use this value, please set `time_window` to 0 to use the `recommended_time_window`.
Tag:
allOf:
- type: object
properties:
id:
type: string
readOnly: true
summary:
type:
- string
- 'null'
readOnly: true
description: 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.
type:
type: string
readOnly: true
description: A string that determines the schema of the object. This must be the standard name for the entity, suffixed by `_reference` if the object is a reference.
self:
type:
- string
- 'null'
readOnly: true
format: url
description: the API show URL at which the object is accessible
html_url:
type:
- string
- 'null'
readOnly: true
format: url
description: a URL at which the entity is uniquely displayed in the Web app
- type: object
properties:
type:
type: string
description: The type of object being created.
default: tag
enum:
- tag
label:
type: string
description: The label of the tag.
maxLength: 191
required:
- label
- type
example:
type: tag
label: Batman
Reference:
allOf:
- $ref: '#/components/schemas/Tag/allOf/0'
- type: object
required:
- type
- id
responses:
Unauthorized:
description: '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.
'
content:
application/json:
schema:
$ref: '#/components/responses/Conflict/content/application~1json/schema'
Forbidden:
description: 'Caller is not authorized to view the requested resource.
While your authentication is valid, the authenticated user or token does not have permission to perform this action.
'
content:
application/json:
schema:
$ref: '#/components/responses/Conflict/content/application~1json/schema'
Conflict:
description: The request conflicts with the current state of the server.
content:
application/json:
schema:
type: object
properties:
error:
type: object
properties:
code:
type: integer
readOnly: true
message:
type: string
readOnly: true
description: Error message string
errors:
type: array
readOnly: true
items:
type: string
readOnly: true
description: Human-readable error details
example:
message: Not Found
code: 2100
NotFound:
description: The requested resource was not found.
content:
application/json:
schema:
$ref: '#/components/responses/Conflict/content/application~1json/schema'
ArgumentError:
description: Caller provided invalid arguments. Please review the response for error details. Retrying with the same arguments will *not* work.
content:
application/json:
schema:
$ref: '#/components/responses/Conflict/content/application~1json/schema'
parameters:
offset_after:
name: after
in: query
required: false
description: Cursor to retrieve next page; only present if next page exists.
schema:
type: string
id:
name: id
description: The ID of the resource.
in: path
required: true
schema:
type: string
header_Accept:
name: Accept
description: The `Accept` header is used as a versioning header.
in: header
required: true
schema:
type: string
default: application/vnd.pagerduty+json;version=2
offset_before:
name: before
in: query
required: false
description: Cursor to retrieve previous page; only present if not on first page.
schema:
type: string
header_Content-Type:
name: Content-Type
in: header
required: true
schema:
type: string
default: application/json
enum:
- application/json
offset_total:
name: total
in: query
required: false
description: '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://developer.pagerduty.com/docs/rest-api-v2/pagination/) for more information.
'
schema:
default: false
type: boolean
services:
name: service_ids[]
in: query
description: An array of service IDs. Only results related to these services will be returned.
explode: true
schema:
type: array
items:
type: string
offset_limit:
name: limit
in: query
required: false
description: The number of results per page.
schema:
type: integer
securitySchemes:
api_key:
type: apiKey
name: Authorization
in: header
description: The API Key with format `Token token=<API_KEY>`