PagerDuty Cheat Sheet
Key concepts and CLI/API usage for configuring PagerDuty services, escalation policies, on-call schedules, and incident response workflows.
2 PagesIntermediateJan 28, 2026
Core Concepts
The building blocks of a PagerDuty account.
- Service- A monitored component (e.g. an API) that receives alerts and maps to an integration
- Integration- A connection between a monitoring tool (Datadog, Prometheus, email) and a Service, each with its own integration key
- Escalation Policy- Ordered rules defining who is notified and when if an incident is not acknowledged
- On-Call Schedule- A rotation of users assigned to be paged during specific time windows
- Incident- A triggered alert requiring action; has states Triggered, Acknowledged, Resolved
- Urgency- High or Low; controls whether notifications interrupt (push/SMS/phone) or are low-priority
- Event Orchestration- Rules engine that routes, suppresses, or enriches events before they create incidents
Events API v2 (Trigger/Resolve)
Send alerts programmatically to a PagerDuty service.
bash
# Trigger an incidentcurl -X POST https://events.pagerduty.com/v2/enqueue \ -H 'Content-Type: application/json' \ -d '{ "routing_key": "<INTEGRATION_KEY>", "event_action": "trigger", "dedup_key": "db-cpu-high-01", "payload": { "summary": "CPU usage above 90% on db-01", "source": "monitoring-agent", "severity": "critical" } }'# Resolve the same incident using dedup_keycurl -X POST https://events.pagerduty.com/v2/enqueue \ -H 'Content-Type: application/json' \ -d '{"routing_key":"<INTEGRATION_KEY>","event_action":"resolve","dedup_key":"db-cpu-high-01"}'
REST API (Incidents)
Query and manage incidents via the PagerDuty REST API.
bash
# List open incidents (requires Authorization: Token token=<API_KEY>)curl -H 'Authorization: Token token=<API_KEY>' \ -H 'Content-Type: application/json' \ 'https://api.pagerduty.com/incidents?statuses[]=triggered&statuses[]=acknowledged'# Acknowledge an incidentcurl -X PUT https://api.pagerduty.com/incidents/<INCIDENT_ID> \ -H 'Authorization: Token token=<API_KEY>' \ -H 'Content-Type: application/json' \ -H 'From: [email protected]' \ -d '{"incident":{"type":"incident_reference","status":"acknowledged"}}'
Terraform Provider Basics
Manage PagerDuty resources as code.
- pagerduty_service- Resource block defining a service, its escalation_policy, and alert_creation setting
- pagerduty_escalation_policy- Defines rule blocks with target user/schedule IDs and escalation_delay_in_minutes
- pagerduty_schedule- Defines layers with users, rotation_virtual_start and rotation_turn_length_seconds
- pagerduty_service_integration- Attaches a vendor integration (e.g. Datadog) to a service, generating an integration key
- terraform import- Bring existing PagerDuty resources under Terraform state before making changes
Event Orchestration Rules (API)
Programmatically create routing rules that suppress noise and set dynamic priority before an event becomes an incident.
bash
# Create a global orchestrationcurl -X POST 'https://api.pagerduty.com/event_orchestrations' \ -H 'Authorization: Token token=<API_KEY>' \ -H 'Content-Type: application/json' \ -d '{"orchestration":{"name":"Prod Routing","description":"Route prod alerts"}}'# Add a rule set that suppresses low-severity noise and sets prioritycurl -X PUT 'https://api.pagerduty.com/event_orchestrations/<ID>/router' \ -H 'Authorization: Token token=<API_KEY>' \ -H 'Content-Type: application/json' \ -d '{ "orchestration_path": { "sets": [{ "id": "start", "rules": [{ "label": "Suppress info-level noise", "conditions": [{"expression": "event.severity matches '\''info'\''"}], "actions": {"suppress": true} }, { "label": "Route DB alerts to db-team", "conditions": [{"expression": "event.custom_details.team matches '\''db'\''"}], "actions": {"route_to": "<SERVICE_ID_DB>"} }] }] } }'
Incident Workflows API
Automate post-trigger actions (Slack posts, status page updates, runbook links) with reusable workflow definitions.
bash
# List incident workflowscurl -H 'Authorization: Token token=<API_KEY>' \ 'https://api.pagerduty.com/incident-workflows'# Manually trigger a workflow instance against a live incidentcurl -X POST 'https://api.pagerduty.com/incident-workflows/<WORKFLOW_ID>/instances' \ -H 'Authorization: Token token=<API_KEY>' \ -H 'Content-Type: application/json' \ -d '{ "incident_workflow_instance": { "incident": {"id": "<INCIDENT_ID>", "type": "incident_reference"}, "workflow": {"id": "<WORKFLOW_ID>", "type": "workflow_reference"} } }'
Change Events API
Correlate deploys and config changes with incidents by sending non-alerting change events tied to a service.
bash
curl -X POST https://events.pagerduty.com/v2/change/enqueue \ -H 'Content-Type: application/json' \ -d '{ "routing_key": "<INTEGRATION_KEY>", "payload": { "summary": "Deployed api-gateway v2.14.0", "source": "ci-pipeline", "timestamp": "2026-07-21T14:03:00Z", "custom_details": {"commit": "a1b2c3d", "environment": "production"} }, "links": [{"href": "https://github.com/org/repo/commit/a1b2c3d", "text": "View commit"}] }'# Change events appear on the incident timeline to speed up root-cause correlation
Advanced API & Reliability Concepts
Lesser-known mechanisms that matter once PagerDuty is wired into real production alerting.
- alert_grouping_parameters- Service-level config (time-based, content-based, or intelligent) that auto-merges related alerts into one incident to reduce noise
- Response Plays- Predefined bundles of responders, subscribers, and status updates that can be attached to an incident with one action
- Maintenance Windows- Time-boxed suppression of a service's alerts (e.g. during planned deploys) created via /maintenance_windows
- Idempotency via dedup_key- Events API v2 enqueue calls are safe to retry; the same dedup_key updates the existing incident rather than creating duplicates
- Webhooks v3 (Subscriptions)- Account/service-scoped subscriptions delivering signed payloads (X-PagerDuty-Signature) for incident.triggered, .acknowledged, .resolved, etc.
- Status Dashboards- Curated, filterable views (by team/service/urgency) for NOC-style situational awareness, distinct from public status pages
- Priority vs Urgency- Priority (P1-P5) is a business-impact label set by rules/responders; Urgency drives actual notification delivery and can differ from priority
Analytics & Postmortems API
Pull incident metrics (MTTA/MTTR) and postmortem content for reliability reporting.
bash
# Aggregate incident metrics by service for the last 30 dayscurl -X POST 'https://api.pagerduty.com/analytics/metrics/incidents/services' \ -H 'Authorization: Token token=<API_KEY>' \ -H 'Content-Type: application/json' \ -d '{ "filters": { "created_at_start": "2026-06-21T00:00:00Z", "created_at_end": "2026-07-21T00:00:00Z", "service_ids": ["<SERVICE_ID>"] } }'# Response includes mean_seconds_to_first_ack, mean_seconds_to_resolve, total_incident_count# Fetch a postmortem (Postincident) document for a resolved incidentcurl -H 'Authorization: Token token=<API_KEY>' \ 'https://api.pagerduty.com/incidents/<INCIDENT_ID>/postmortem'
Pro Tip
Use dedup_key consistently per alert source so repeated Events API triggers update the same incident instead of spawning duplicates, and always send a matching resolve event when the underlying condition clears.
Was this cheat sheet helpful?
Explore Topics
#PagerDuty#PagerDutyCheatSheet#DevOps#Intermediate#CoreConcepts#Events#API#Trigger#APIs#CommandLine#CheatSheet#SkillVeris
