Escalation Policy Basics

Escalation policies make sure the right people are notified at the right time. They connect services to schedules. A service can only have one escalation policy, though an escalation policy can be associated with multiple services.

Create an Escalation Policy

Escalation policies are found under ConfigurationEscalation Policies. There is a Default escalation policy in the account from the start. The Account Owner will be the only target on the default escalation policy, though this can be changed at any time.

To create an escalation policy:

  1. Go to Configuration → Escalation Policies.
  2. Click New Escalation Policy.
  3. Name your escalation policy. Add a description (optional).
  4. Select the targets (on-call schedules and/or users) you want to notify when an incident is triggered.
  5. If desired, you can add a second level to the escalation policy. To do this, choose the number of minutes that should pass before the incident escalates. This time period is the escalation timeout. Incidents will not escalate if they are acknowledged or resolved before the timeout is reached.
  6. Then click Add a new Escalation Rule to create the second level.
  7. Select targets for the second escalation rule.
  8. Configure additional escalation rules as required.
  9. Click Save.

Recommended:

We suggest configuring your policy to repeat. To do this, check the box next to If no one acknowledges, repeat this policy __. Then, select the number of times to repeat. An escalation policy can be repeated up to 9 times.

Escalation Policy Example

In the example below, if an on-call user in the Primary On-Call Schedule schedule does not acknowledge an incident in 30 minutes, it will escalate to Jason Collison. The escalation timeout at the second level is also 30 minutes. Jason will have 30 minutes to acknowledge the incident before it escalates and starts over from the beginning of the policy. This escalation policy is set to repeat 9 times.

Escalation Targets and Limitations

You can select users or schedules as targets on an escalation policy. When an incident triggers, we'll attempt to notify responders at the first level of the escalation policy. If the incident is not acknowledged within the escalation timeout period, it will escalate to next escalation level, and so on down the line.

If nobody is on-call in the first level, we will assign the incident to the on-call responder at the subsequent escalation level.

Important Note

An incident follows the escalation policy as it was at the time the incident triggered. Any changes to the escalation policy made after an incident triggers will not affect open incidents (triggered or acknowledged).

Limits on escalation policies

  • You can add up to 20 escalation rules to an escalation policy.
  • You have the option to repeat an escalation policy 9 times. Once an escalation policy reaches the amount of loops configured, the incident will stay assigned to the last user and will not continue to notify once it has cycled through all of the responder's contact methods.
  • You can notify up to 10 users/schedules (50 on Standard and Enterprise plans) in a single escalation rule.
  • The minimum escalation timeout is 1 minute if there is a single target on an escalation rule. Alternatively, if there is more than one target in an escalation level the minimum escalation timeout is 5 minutes. These restrictions are displayed in the web UI.

Notify Multiple Users at Once

Multi-user notifications will notify multiple users at once when an incident is triggered or escalated, and can be configured within an escalation policy. To notify 2 or more users at once, you will want to configure an escalation policy so that multiple on-call schedules and/or users are in the same escalation level.

Using on-call schedules for multi-user notifications

An important concept to grasp is that only one user can be on-call per schedule. A natural first instinct would be to add multiple layers to a schedule, however the way PagerDuty's system works, the lowest layer on a schedule takes precedence over any others.

The following screenshot demonstrates what will happen if multiple layers are stacked on top of each other (Layer 3 takes precedence over Layers 1 and 2):

Configuring your escalation policy to notify 2 or more users at once

To notify 2 or more users at once, you will want to set up an escalation policy with multiple on-call schedules/users on the same escalation level.

  1. Go to Configuration → Escalation Policies.

  2. Click New Escalation Policy to create a new escalation policy, or click an existing escalation policy's gear icon and then Edit to edit an existing one.

  3. Click in the field below Notify the following users or schedules and select the on-call schedules and/or users you want to notify when an incident is triggered or escalated.

  4. Click Save and you're done!

Note

If you have Live Call Routing enabled to Connect Directly and there is more than one responder on an escalation level, PagerDuty will randomly cycle through all responders on at that level. If an incident triggers via Live Call Routing (if either no one answers, or you've selected "Leave a Message"), however, all users on an escalation level can expect to receive notifications via their configured notification methods.

Choosing an on-call schedule or a user for multi-user notifications

Select a user if you always want that person to be notified when an incident is assigned and/or escalated to an escalation level.

Select an on-call schedule if you want to notify the user who is on-call from that schedule.

Limitations for multi-user notifications

Notifying too many users at once runs the risk of creating confusion about who owns an incident. With this is mind, multi-user notifications are limited to 50 users or schedules on Standard and Enterprise plans and 10 users or schedules on Lite and Basic plans.

This topic addresses best practices about when to notify one user vs. many users.

Escalation Policy Basics