PagerDuty Services

PagerDuty Services

Overview

Services in PagerDuty represent the applications, components, or infrastructure that your team is responsible for. Each service has an escalation policy, integrations (event sources), and configuration for how incidents are created and grouped. Services are the primary organizational unit for routing alerts to the right responders.

Key Concepts

Service Status

| Status | Description | |--------|-------------| | active | Service is live and will create incidents from alerts | | warning | Service has acknowledged but unresolved incidents | | critical | Service has triggered (unacknowledged) incidents | | maintenance | Service is in a maintenance window; alerts are suppressed | | disabled | Service is disabled; no incidents will be created |

Integrations

Integrations are the event sources that feed into a service. Each integration has a unique integration_key used to route events:

• Events API v2 -- Generic integration for any monitoring tool
• Email -- Incidents created from emails sent to a service-specific address
• Vendor-specific -- Pre-built integrations (Datadog, CloudWatch, Nagios, etc.)

Alert Grouping

Services can be configured to automatically group related alerts into a single incident:

| Mode | Description | |------|-------------| | intelligent | PagerDuty ML groups related alerts automatically | | time | Alerts within a time window are grouped together | | content_based | Alerts with matching fields are grouped |

Dependencies

Service dependencies map upstream and downstream relationships between services. This helps identify blast radius during incidents and understand service topology.

API Patterns

List Services

pagerduty_list_services

Parameters:

• query -- Search by service name
• team_ids[] -- Filter by team
• include[] -- Include related resources (escalation_policies, teams, integrations)
• sort_by -- Sort field (name)
• limit / offset -- Pagination

Example response:

{
  "services": [
    {
      "id": "PSVC123",
      "name": "Payment API",
      "status": "active",
      "description": "Payment processing service",
      "escalation_policy": {
        "id": "PPOLICY1",
        "summary": "Engineering On-Call"
      },
      "alert_creation": "create_alerts_and_incidents",
      "alert_grouping_parameters": {
        "type": "intelligent"
      },
      "teams": [
        {
          "id": "PTEAM01",
          "summary": "Platform Team"
        }
      ]
    }
  ],
  "limit": 25,
  "offset": 0,
  "total": 1,
  "more": false
}

Get Service Details

pagerduty_get_service

Parameters:

• id -- Service ID
• include[] -- Include integrations, escalation_policies, teams

Create Service

pagerduty_create_service

Parameters:

• name -- Service name (required)
• description -- Service description
• escalation_policy -- Escalation policy reference (required)
• alert_creation -- create_alerts_and_incidents or create_incidents
• alert_grouping_parameters -- Alert grouping configuration

Update Service

pagerduty_update_service

Parameters:

• id -- Service ID
• name -- Updated name
• description -- Updated description
• status -- active or disabled
• alert_grouping_parameters -- Updated grouping config

List Service Dependencies

pagerduty_list_service_dependencies

Parameters:

• id -- Service ID

Returns upstream (depends on) and downstream (depended on by) service relationships.

Maintenance Windows

List Maintenance Windows

pagerduty_list_maintenance_windows

Parameters:

• service_ids[] -- Filter by service
• filter -- ongoing, future, past, or all
• query -- Search by description

Create Maintenance Window

pagerduty_create_maintenance_window

Parameters:

• start_time -- Start time (ISO 8601)
• end_time -- End time (ISO 8601)
• description -- Description of the maintenance
• services -- List of service references

Example request body:

{
  "maintenance_window": {
    "type": "maintenance_window",
    "start_time": "2026-03-28T02:00:00Z",
    "end_time": "2026-03-28T06:00:00Z",
    "description": "Database upgrade - v12 to v15",
    "services": [
      {
        "id": "PSVC123",
        "type": "service_reference"
      }
    ]
  }
}

Common Workflows

Service Health Check

1. Call pagerduty_list_services to get all services
2. Check status field for each service (critical, warning, active)
3. For services in critical or warning status, list their incidents
4. Report services with active incidents and their severity

Creating a New Service

1. Identify or create the escalation policy
2. Create the service with pagerduty_create_service
3. Add integrations for monitoring tools
4. Configure alert grouping as appropriate
5. Set up service dependencies

Scheduling Maintenance

1. Identify affected services
2. Create a maintenance window with pagerduty_create_maintenance_window
3. During the window, alerts on those services are suppressed
4. After the window ends, normal alerting resumes automatically

Mapping Service Dependencies

1. List services to find the target service
2. Call pagerduty_list_service_dependencies for the service
3. Visualize upstream and downstream relationships
4. Use during incidents to assess blast radius

Error Handling

Service Not Found

Cause: Invalid service ID Solution: List services to find the correct ID

Cannot Delete Service with Active Incidents

Cause: Service has unresolved incidents Solution: Resolve all incidents before disabling or deleting

Duplicate Service Name

Cause: A service with the same name already exists Solution: Use a unique name or update the existing service

Best Practices

• Use descriptive service names that match your infrastructure topology
• Configure intelligent alert grouping to reduce incident noise
• Map service dependencies for faster incident triage
• Schedule maintenance windows for planned changes to suppress false alerts
• Assign each service to a team for clear ownership
• Review service configuration periodically as infrastructure evolves
• Use include[]=integrations to verify monitoring sources are connected

Related Skills

• [api-patterns](../api-patterns/SKILL.md) - Pagination and error handling
• [incidents](../incidents/SKILL.md) - Incidents on services
• [oncall](../oncall/SKILL.md) - Escalation policies assigned to services
• [alerts](../alerts/SKILL.md) - Alerts routed to services
• [analytics](../analytics/SKILL.md) - Per-service performance metrics