---
name: "PagerDuty Services"
description: >
  Use this skill when working with PagerDuty services -- service catalog,
  service configuration, integrations, dependencies, maintenance windows,
  and service health monitoring.
when_to_use: "When working with service catalog, service configuration, integrations, dependencies, maintenance windows, and service health monitoring in PagerDuty services"
triggers:
  - pagerduty service
  - service catalog
  - service dependencies
  - service integrations
  - maintenance window
  - service health
  - service status
---

# 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:**

```json
{
  "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:**

```json
{
  "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