Skip to main content

​
Overview

The create_alert_grouping_setting tool creates a new alert grouping setting that defines how alerts should be automatically grouped into incidents for specific services.
This is a write tool that creates a new configuration in your PagerDuty account. You must enable write tools with the --enable-write-tools flag to use this tool.

​
Parameters

​
name
string
A short-form name for labeling the alert grouping setting.Example: "Production API Grouping"
​
description
string
A description providing more information about the alert grouping setting.Example: "Groups API alerts by component and severity"
​
type
string
required
The type of alert grouping configuration. Must be one of:
  • content_based - Group by matching field values
  • content_based_intelligent - Intelligent grouping with field matching
  • intelligent - AI-powered intelligent grouping
  • time - Group alerts within a time window
Example: "content_based"
​
config
object
required
The configuration for the alert grouping setting. Structure varies by type.
​
services
array
required
Array of service references that this alert grouping setting applies to. Note: content_based_intelligent type allows only one service.Example:
[
  {"id": "PSVC123", "type": "service_reference"},
  {"id": "PSVC456", "type": "service_reference"}
]

​
Response

Returns the created alert grouping setting object with all fields including generated ID and timestamps.
​
id
string
The unique identifier of the newly created alert grouping setting
​
type
string
The type of alert grouping configuration
​
name
string
The name of the alert grouping setting
​
description
string
The description of the alert grouping setting
​
config
object
The configuration for the alert grouping setting
​
services
array
Array of service references
​
created_at
datetime
The ISO8601 date/time when the setting was created
​
updated_at
datetime
The ISO8601 date/time when the setting was last updated

​
Example Usage

"Create a content-based alert grouping for service PSVC123 that groups by component and severity"

​
Use Cases

  • Reduce alert noise - Group related alerts into single incidents
  • Standardize grouping - Apply consistent grouping rules across services
  • Service-specific rules - Customize grouping for different service types
  • Optimize response - Ensure responders see related alerts together
  • Test grouping strategies - Try different configurations to find optimal settings

​
Configuration Examples

​
Content-Based Grouping

{
  "type": "content_based",
  "config": {
    "aggregate": "all",
    "fields": ["component", "environment"],
    "time_window": 3600
  },
  "services": [{"id": "PSVC123"}]
}

​
Time-Based Grouping

{
  "type": "time",
  "config": {
    "timeout": 1800
  },
  "services": [{"id": "PSVC123"}]
}

​
Intelligent Grouping

{
  "type": "intelligent",
  "config": {
    "time_window": 0,
    "iag_fields": ["summary"]
  },
  "services": [{"id": "PSVC123"}]
}

​
Important Notes

  • The content_based_intelligent type supports only one service per setting
  • Setting time_window to 0 uses PagerDuty’s recommended time window
  • Field names must match the structure of alerts sent to your service
  • Alert Grouping features are available only on certain PagerDuty plans
  • Each service can have only one active alert grouping setting

Build docs developers (and LLMs) love

Get started for freeTalk to us