Skip to main content

​
Overview

The update_alert_grouping_setting tool modifies an existing alert grouping setting, allowing you to change how alerts are grouped into incidents for specific services.
This is a write tool that modifies an existing configuration in your PagerDuty account. You must enable write tools with the --enable-write-tools flag to use this tool.

​
Parameters

​
setting_id
string
required
The unique identifier of the alert grouping setting to update.Example: "PAGRSET1"
​
name
string
A short-form name for labeling the alert grouping setting.Example: "Updated Production Grouping"
​
description
string
A description providing more information about the alert grouping setting.Example: "Updated to group by host and service"
​
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. See Create Alert Grouping Setting for detailed configuration options.Example for content-based:
{
  "aggregate": "all",
  "fields": ["host", "service"],
  "time_window": 1800
}
​
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"}]

​
Response

Returns the updated alert grouping setting object.
​
id
string
The unique identifier of the 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 (reflects this update)

​
Example Usage

"Update alert grouping setting PAGRSET1 to use a 30 minute time window"

​
Use Cases

  • Optimize grouping - Adjust time windows or fields based on alert patterns
  • Fix configuration - Correct misconfigured grouping rules
  • Adapt to changes - Update grouping as alert structure evolves
  • Test improvements - Experiment with different grouping strategies
  • Service changes - Update which services use the grouping setting

​
Update Examples

​
Update Time Window

{
  "setting_id": "PAGRSET1",
  "type": "content_based",
  "config": {
    "aggregate": "all",
    "fields": ["component"],
    "time_window": 1800
  },
  "services": [{"id": "PSVC123"}]
}

​
Change to Intelligent Grouping

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

​
Update Grouping Fields

{
  "setting_id": "PAGRSET1",
  "type": "content_based",
  "config": {
    "aggregate": "any",
    "fields": ["host", "service", "environment"],
    "time_window": 3600
  },
  "services": [{"id": "PSVC123"}]
}

​
Important Notes

  • Updates replace the entire configuration - include all required fields
  • Changes take effect immediately for new alerts
  • Existing incidents are not affected by the update
  • The content_based_intelligent type supports only one service
  • Setting time_window to 0 uses PagerDuty’s recommended time window
  • Ensure field names match your alert structure
Before updating, consider reviewing the current configuration with Get Alert Grouping Setting to understand the existing setup.

Build docs developers (and LLMs) love

Get started for freeTalk to us