PagerDuty

PagerDuty

This connector works with one PagerDuty account through the REST API v2 (https://api.pagerduty.com, or https://api.eu.pagerduty.com for accounts in the EU service region): incidents with their notes, timeline and alerts, services, escalation policies, who is on call, schedules, users, teams, priorities and incident analytics. It can acknowledge, resolve, reassign and escalate incidents, change their title, urgency or priority, add notes and open new incidents.

Setup (about 3 minutes)

1. Pick the key type. A user token acts as one person and sees what that person sees: in PagerDuty open your avatar, My Profile, User Settings, Create API User Token. A general access key acts for the whole account and needs an admin: Integrations, API Access Keys, Create New API Key. Tick Read-only there for a connector that only reads.
2. Paste the key into PAGERDUTY_API_KEY. It is sent as Authorization: Token token=<key> together with Accept: application/vnd.pagerduty+json;version=2.
3. Set PAGERDUTY_API_HOST to api.pagerduty.com, or to api.eu.pagerduty.com when your PagerDuty address is in the EU region (your account's service region is shown under Account Settings). A key only works on its own region's host.
4. With a general access key, also set PAGERDUTY_FROM_EMAIL to the email of a PagerDuty user: PagerDuty requires it in the From header of every change and records the change under that user. A user token does not need it.
5. Check the setup with pagerduty_list_services. pagerduty_get_current_user only works with a user token; with a general access key PagerDuty answers 400 because the key belongs to no user.

Changes page people and close incidents: confirm first. pagerduty_acknowledge_incident, pagerduty_resolve_incident, pagerduty_reassign_incident, pagerduty_escalate_incident, pagerduty_update_incident, pagerduty_add_incident_note, pagerduty_create_incident change live incidents. Acknowledging stops the paging, resolving closes the incident, reassigning and escalating page other people, creating an incident pages the on-call responders of the service. Before each call, show the user the incident (number and title) and the change and wait for their yes. Nothing here deletes anything. For a read-only setup use a read-only general access key, or switch those tools off.

How to work

1. Open incidents: pagerduty_list_incidents with statuses ["triggered", "acknowledged"]. Then pagerduty_get_incident, pagerduty_list_incident_log_entries (timeline), pagerduty_list_incident_alerts (what the monitoring tool sent) and pagerduty_list_incident_notes.
2. Who is on call now: pagerduty_list_oncalls without dates; for a team's schedule pagerduty_list_schedules then pagerduty_get_schedule. Escalation levels: pagerduty_list_escalation_policies and pagerduty_get_escalation_policy.
3. Directory: pagerduty_list_services, pagerduty_get_service, pagerduty_list_users, pagerduty_get_user, pagerduty_list_teams, pagerduty_list_priorities.
4. Acting: pagerduty_acknowledge_incident, pagerduty_resolve_incident, pagerduty_reassign_incident (to a user id), pagerduty_escalate_incident (to a level), pagerduty_update_incident (title, urgency, priority by name), pagerduty_add_incident_note, pagerduty_create_incident (on a service).
5. Reporting: pagerduty_get_incident_analytics (per incident) and pagerduty_get_incident_metrics (totals, per day, week or month). Both need a PagerDuty plan that includes Analytics, and a user token must filter by service_ids or team_ids.

Ids and dates: ids are short strings such as PT4KHLK; the incident number (#1234) is not an id. Dates are ISO 8601. pagerduty_list_incidents covers the last 30 days unless you pass since and until (at most 6 months apart) or date_range all.

Paging: lists take limit (up to 100) and offset; while the answer has more: true, call again with offset + limit. Analytics pages with starting_after.

Common errors

• 401: the key is wrong, was deleted, or belongs to the other region's host.
• 400 with "From": a general access key made a change without PAGERDUTY_FROM_EMAIL, or the email is not a user of the account.
• 400 on pagerduty_get_current_user: the key is a general access key.
• 403: a read-only key tried a change, the user's role does not allow it, or the plan lacks the feature (teams, analytics).
• 404: no such id on this account. 429: too many requests; wait and retry.

Out of scope here: the Events API (sending alerts with an integration's routing key is what monitoring tools do, on a separate host with a separate key; pagerduty_create_incident covers opening an incident by hand), creating or changing services, schedules, escalation policies and users, status pages, incident workflows, webhooks and all deletes.