PagerDuty Documentation

Abilities

"Abilities" describes your account's capabilities by feature name. For example "teams".

An ability may be available to your account based on things like your pricing plan or account state.

Add-ons

Developers can write their own functionality to insert into PagerDuty's UI.

Audit Record

The Audit Trail data is a collection of Audit Records.

Audit API provides read-only access to audit records generated by actions (e.g. changes such as create, update, delete) to PagerDuty resources (e.g. PagerDuty objects such as escalation policies, services, schedules, teams, users, etc.).

Business Services

Business Services model capabilities that span multiple technical Services and that may be owned by several different teams.

Mapping technical Services to Business Services gives responders context on an Incident’s impact to the business.

Impactors

A Business Service may be become impacted by one or more Impactors. An Impactor represents an entity that could be causing the functionality represented by the Business Service to be degraded or broken.

The definition of an Impactor is generic, but is currently limited to Incidents.

Escalation Policies

An Escalation Policy determines what User or Schedule will be Notified and in what order. This will happen when an Incident is triggered.

Escalation Policies can be used by one or more Services.

Escalation Rules

An Escalation Policy is made up of multiple Escalation Rules. Each Escalation Rule represents a level of On-Call duty.

It specifies one or more Users or Schedules to be notified when an unacknowledged Incident reaches that Escalation Rule.

The first Escalation Rule in the Escalation Policy is the User that will be notified about the triggered Incident.

If all On-Call User for a given Escalation Rule have been acknowledged of an Incident and the Escalation Rule's escalation delay has elapsed, the Incident escalates to the next Escalation Rule.

Event Orchestrations

A Global Event Orchestrations allow you define a set of Event Rules, so that when you ingest events using the Orchestration's Routing Key your events will be routed to the correct Service, based on the event's content.

A Service Orchestration allows you to create a set of Event Rules specific to a Service. The Service Orchestration evaluates Events sent to this Service against each of its rules, beginning with the rules in the "start" set. When a matching rule is found, it can modify and enhance the event and can route the event to another set of rules within this Service Orchestration for further processing.

Extensions

A PagerDuty Extension represents an instance of an Extension Schema on a object that an Extension can be attached to, such as a Service.

An example of an Extension would be a Generic Webhook endpoint, or the Slack Extension.

Extension Schema

An Extension Schema represents a specific type of outbound extension such as Generic Webhook, Slack, ServiceNow.

Extension Schemas will contain template configuration information that is required to instantiate an instance of the Extension Schema as an Extension.

If an Extension Schema already has a preconfigured url, the Extension will not have to configure one.

In addition, if the Extension Schema has a config object, the Extension will need to provide config values based on what the Extension Schema indicates are required for the config.

For Generic V2 Webhooks and Custom Incident Actions, there is an option to add custom headers. Customers can define pairs of header names and header values. These custom headers will be sent as HTTP headers in the request to the specified endpoint. This can be used to add an Authorization header to webhook sent from Pagerduty.

Some Extension Schemas that require OAuth Authorization to be setup, such as the Slack Extension, cannot be configured through the API.

Incidents

An Incident represents a problem or an issue that needs to be addressed and resolved.

Incidents can be thought of as a problem or an issue within your Service that needs to be addressed and resolved, they are normalized and de-duplicated.

Incidents can be triggered, acknowledged, or resolved, and are assigned to a User based on the Service's Escalation Policy.

A triggered Incident prompts a Notification to be sent to the current On-Call User(s) as defined in the Escalation Poicy used by the Service.

Incidents are triggered through the Events API or are created by Integrations.

Licenses

A License may be associated to a User as well as a collection of products. The User assigned to a License may be granted access to PagerDuty features and products according to what the License dictates.

Responder Requests

Responder Requests are a request for a specific User to respond to the Incident.

Notes

Notes are appended to Incidents to add context for responders.

Status Updates

Status Updates are a updates for stakeholders who are not responding to incidents.

Snooze

Snoozing an Incident will re-trigger it after a specified amount of time.

Alerts

When PagerDuty receives a qualifying event (from a monitoring tool, for example), it triggers an alert, which in turn triggers an incident. Multiple alerts can be aggregated into a single incident for triage, which streamlines incident handoff between teams, centralizes critical information, and reduces notification fatigue.

Past Incidents

Past Incidents allow Responders to view past resolved Incidents that have similar metadata and were generated on the same Service as their current active Incident. Past Incidents add helpful context for accurate triage, which can lead to shorter resolution time. Responders can see who was involved in a previous Incident, when these types of Incidents happened, and dive into Incident details to discover the remediation steps that were taken.

Log Entries

Updates to an Incident generate Log Entries that capture the changes to an Incident over time, whether these changes were prompted by a User, an Integration, or were performed automatically.

Log entries give you more insight into how your team or organization is handling your Incidents.

Log entry data includes details about the event(s) that affected the Incident throughout its lifecycle, such as:

The data contained in events sent by the Integration.
Which Users were notified and at what time.
How a User was notified
What User(s) acknowledged or resolved the Incident
Any automatic actions that occurred to the Incident
Any other manual User actions, such as a reassignment or a note

Log entries cannot be created directly through the API; they are a result of other actions. The API provides read-only access to the Log Entries generated by PagerDuty.

Maintenance Windows

A Maintenance Window is used to temporarily disable one or more Services for a set period of time.

No Incidents will be triggered and no Notifications will be received while a Service is disabled by a Maintenance Window.

Maintenance windows are specified to start at a certain time and end after they have begun. Once started, a Maintenance Window cannot be deleted; it can only be ended immediately to re-enable the Service.

Notifications

A Notification is created when an Incident is triggered or escalated and an Alert is sent to a User.

Notifications are messages containing the details of the Incident, and can be through SMS, email, phone calls, and push notifications.

Notifications cannot be created directly through the API; they are a result of other actions. The API provides read-only access to the Notifications generated by PagerDuty.

OAuth Delegations

An OAuth delegation represents an instance of a user or account's authorization to an app (via OAuth) to access their PagerDuty account. Common apps include the PagerDuty mobile app, Slack, Microsoft Teams, and third-party apps. When an OAuth delegation is deleted or revoked, all its access and refresh tokens are effectively revoked; therefore, the user or the account needs to reauthorize the app again.

On-Calls

An On-Call represents a contiguous unit of time for which a User will be On-Call for a given Escalation Policy and Escalation Rule.

This may be the result of that User always being On-Call for the Escalation Rule, or a block of time during which the computed result of a Schedule on that Escalation Rule puts the User On-Call.

During an On-Call, the User is expected to bear responsibility for responding to any Notifications they receives and working to resolve the associated Incident(s).

On-Calls cannot be created directly through the API; they are the computed result of how Escalation Policies and Schedules are configured. The API provides read-only access to the On-Calls generated by PagerDuty.

Outlier Incident

Outlier Incident provides details on frequent, rare or anomalous Incidents and how often they occur. The following labels are applied underneath the Incident title on the Incident details page:

Frequent: Incident types representing 20% or more of all Incidents in the preceding 30 days.
Rare: Incident types representing 5% or less of all Incidents in the preceding 30 days.
Anomaly: Incident types that have not occurred on the service in the preceding 30 days.

For the purpose of determining which of the labels above to use, Incident data from the 30 days prior to an Incident’s trigger date is used.

Priorities

A Priority is a label representing the importance and impact of an incident. This feature is only available on Standard and Enterprise plans.

Paused Incident Reports

Paused Incident Reports provide service and account level insights on Alerts that have been paused through rules or through auto pause.

Related Incidents provide Responders with the 20 most recent Related Incidents that are impacting other Responders and Services. This feature uses a completely online and real-time machine learning algorithm as well as your Service dependency data to provide these insights, giving Responders an at-a-glance-view of the full breadth and scope of Incident impact.

Response Plays

Response Plays let you create packages of Incident Actions that can be applied to an Incident.

Deprecation Notice: Response Plays have been replaced by the more robust Incident Workflows feature.

Rulesets

Rulesets allow you to route events to an endpoint and create collections of event rules, which define sets of actions to take based on event content.

Schedules

A Schedule determines the time periods that Users are On-Call.

Only On-Call Users are eligible to receive Notifications from Incidents.

The details of the On-Call Schedule specify which single User is On-Call for that Schedule at any given point in time.

Schedules are used by Escalation Policies as an escalation target for a given Escalation Rule.

V2 Layer-Based (Legacy Schedule)

A V2 Schedule consists of one or more Schedule Layers that rotate a group of Users through the same shift at a set interval.

V2 Schedules are accessed at /schedules and use the layer-based model for defining on-call rotations.

V3 Shift-Based (Flexible Schedule)

Flexible Schedules (V3) introduce a more powerful and flexible model for on-call scheduling, replacing the previous layer-based model with a shift-based model.

V3 Schedules are accessed at /v3/schedules and support multiple rotations running simultaneously under one schedule, time-based events that track configuration changes, custom shifts, and overrides.

Flexible Schedules can support complex scheduling scenarios such as weekday/weekend coverage, 24-hour multi-shift coverage, and geography-based rotations.

V3 is currently in Early Access. Register here, and contact your Customer Success Manager to confirm your enrollment.

Rotations

A Rotation is a container within a Flexible Schedule that defines distinct configuration rules Events for on-call coverage.

Multiple rotations can run simultaneously under one schedule, each with its own settings, timezones, and team members. Rotations are made up of Events, which hold the scheduling rules effective for a period of time.

Rotations enable complex scheduling scenarios such as weekday/weekend coverage, 24-hour multi-shift coverage, and geography-based rotations. A schedule can have a maximum of 10 active rotations.

Events

An Event represents a specific configuration of scheduling rules within a Rotation. It defines the actual configurations that put people on call. It contains rules on who is on-call, when they're on-call, how they rotate, and when these rules are effective.

Events have different editing capabilities based on their state: past events are read-only, active events can only be ended, and future events are fully editable. This timeline integrity ensures configuration changes are tracked over time.

A rotation can have up to 5 events, starting now or later. Past events are not counted towards this limit.

Custom Shifts

A Custom Shift is a standalone, one‑off shift added directly to a schedule, bypassing the Rotation mechanism. It explicitly defines start and end times and the assigned member (or an unassigned placeholder). Custom Shifts are suited for ad‑hoc coverage, maintenance windows, or cases where an external system determines on-call assignments and the schedule must reflect that source of truth. Custom Shifts bypass rotation logic but are included in the final schedule of shift assignments.

Overrides

An Override is a temporary substitution that changes the assigned on-call member for a defined time window without modifying the underlying configuration. In Flexible Schedules, an Override can target either a Rotation or a specific Custom Shift, replacing the originally assigned member only for the specified duration. This mechanism supports short-notice swaps, vacation coverage, or partial-day handoffs. An override sits on top of the custom shift or rotation being overridden, and the shift produced are included in the final schedule of shift assignments.

Session Configurations

A session configuration represents an account-level session timeout setting that applies to all users belonging to the account. The configuration consists of two timeouts: idle_session_timeout logs out users after a specified period of inactivity, while absolute_session_timeout defines the maximum period of time a session is considered valid since login. The configuration can be set by type: web, mobile, or for both types. Once a configuration is set for an account, existing sessions are automatically revoked, to ensure all sessions follow the configured timeouts.

If an account does not have session configuration defined, all its users would follow the system-level session defaults: 15 mins idle and 1 hour absolute session timeout, applicable to both web and mobile. These defaults are not accessible via the APIs.

Services

A Service represents an entity you monitor (such as a web Service, email Service, or database Service.)

It is a container for related Incidents that associates them with Escalation Policies.

A Service is the focal point for Incident management; Services specify the configuration for the behavior of Incidents triggered on them.

This behavior includes specifying urgency and performing automated actions based on time of day, Incident duration, and other factors.

Integrations

An Integration is an endpoint (like Nagios, email, or an API call) that generates events, which are normalized and de-duplicated by PagerDuty to create Incidents.

Integrations feed events into Services and provide event management functionality such as filtering and de-duplication.

Teams

A Team is a collection of Users and Escalation Policies that represent a group of people within an organization.

Teams can be used throughout the API and PagerDuty applications to filter information to only what is relevant for one or more teams.

The account must have the Teams ability to use the following endpoints.

Users

Users are members of an Account that have the ability to interact with Incidents and other data on the account.

Users are fundamental agents of different types of actions in PagerDuty. A User can, among other things:

Acknowlege, reassign, snooze, escalate, and resolve Incidents.
Configure Services, Escalation Policies, Integrations, On-Call Schedules, Teams, and more.
Go On-Call for one or more Schedules or Escalation Policies.
Get Alerted and receive Notifications.

Depending on a User's role, they may have access to different parts of the account's data.

Vendors

A Vendor represents a specific type of Integration. AWS CloudWatch, Slack, Datadog, are all examples of Vendors that can be integrated into PagerDuty by making an Integration.

Vendor Integrations (when compared to generic email and API Integrations) are automatically configured with the right API or email filtering settings for inbound events from that Vendor. Some Vendors also have associated Integration Guides on the PagerDuty support site.

Webhooks

Webhook Subscriptions are used to manage the next generation of PagerDuty webhooks: V3 Webhooks.

A Webhook Subscription indicates an interest in a set of outbound events occurring on the PagerDuty platform. Each Webhook Subscription specifies a filter to only match events that occur under the scope of that filter.

Each Webhook Subscription is also associated with a delivery method that specifies how the subscribed events should be delivered. At this time, the only supported type of delivery method is HTTP which delivers the events as an HTTP POST (webhook).

Dedicated Channels

A dedicated channel is a slack channel associated with one and only one incident (1:1 relation), so that every update related to that incident is posted to that channel, making the complete management of the incident possible in one place.

Notification Channels

Incidents can be linked to more than 1 notification Slack channel. A notification Slack channel can be linked to more than 1 incident. This makes keeping up to date with different incidents easier.

API Concepts