# API Concepts Glossary of the resource types and concepts used across the PagerDuty APIs. ## 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](/developer/audit-records-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 **Impactor**s. 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. [*Read more about business Services in the PagerDuty Knowledge Base*](https://support.pagerduty.com/docs/business-services). ## Escalation Policies An Escalation Policy determines what [User](#users) or [Schedule](#schedules) will be [Notified](#notifications) and in what order. This will happen when an [Incident](#incidents) is triggered. Escalation Policies can be used by one or more [Services](#services). ### Escalation Rules An Escalation Policy is made up of multiple Escalation Rules. Each Escalation Rule represents a level of [On-Call](#on-calls) duty. It specifies one or more [Users](#users) or [Schedules](#schedules) to be notified when an unacknowledged [Incident](#incidents) reaches that Escalation Rule. The first Escalation Rule in the Escalation Policy is the [User](#users) that will be [notified](#notifications) about the triggered [Incident](#incidents). If all [On-Call](#on-calls) [User](#users) for a given Escalation Rule have been acknowledged of an [Incident](#incidents) and the Escalation Rule's escalation delay has elapsed, the [Incident](#incidents) escalates to the next Escalation Rule. [*Read more about Escalation Policies in the PagerDuty Knowledge Base*](/incident-management/schedules/escalation-policies). ## 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. [*Read more about Event Orchestrations in the PagerDuty Knowledge Base*](https://support.pagerduty.com/docs/event-orchestration). ## Extensions A PagerDuty Extension represents an instance of an [Extension Schema](#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](#services) 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](#users) based on the [Service](#services)'s [Escalation Policy](#escalation-policies). A triggered Incident prompts a [Notification](#notifications) to be sent to the current [On-Call](#on-calls) [User(s)](#users) as defined in the [Escalation Policy](#escalation-policies) used by the [Service](#services). Incidents are triggered through the [Events API](/developer/events-api-v2-overview) or are created by Integrations. [*Read more about Incidents in the PagerDuty Knowledge Base*](/incident-management/incidents/overview). ### 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](#users) 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](#log-entries) that capture the changes to an Incident over time, whether these changes were prompted by a [User](#users), an [Integration](#integrations), or were performed automatically. Log entries give you more insight into how your [team](#teams) or organization is handling your [Incidents](#incidents). Log entry data includes details about the event(s) that affected the [Incident](#incidents) throughout its lifecycle, such as: - The data contained in events sent by the [Integration.](#integrations) - Which [Users](#users) were [notified](#notifications) and at what time. - How a User was [notified](#notifications) - What [User(s)](#users) acknowledged or resolved the [Incident](#incidents) - Any automatic actions that occurred to the [Incident](#incidents) - Any other manual [User](#users) 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](#services) for a set period of time. No [Incidents](#incidents) will be triggered and no [Notifications](#notifications) will be received while a [Service](#services) 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](#services). [*Read more about Maintenance Windows in the PagerDuty Knowledge Base*](/incident-management/services/maintenance-windows). ## Notifications A Notification is created when an [Incident](#incidents) is triggered or escalated and an [Alert](#alerts) is sent to a [User.](#users) Notifications are messages containing the details of the [Incident](#incidents), 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. [*Read more about Notifications in the PagerDuty Knowledge Base*](/incident-management/notifications/notification-content-and-behavior). ## 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](#users) will be On-Call for a given [Escalation Policy](#escalation-policies) and [Escalation Rule](#escalation-rules). This may be the result of that [User](#users) always being On-Call for the [Escalation Rule](#escalation-policies), or a block of time during which the computed result of a [Schedule](#schedules) on that [Escalation Rule](#escalation-policies) puts the User On-Call. During an On-Call, the [User](#users) is expected to bear responsibility for responding to any [Notifications](#notifications) they receives and working to resolve the associated [Incident(s)](#incidents). On-Calls cannot be created directly through the API; they are the computed result of how [Escalation Policies](#escalation-policies) and [Schedules](#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 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.](#incidents) **Deprecation Notice**: Response Plays have been replaced by the more robust [Incident Workflows](/ai-automation/automation/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. [*Read more about Rulesets in the PagerDuty Knowledge Base*](https://support.pagerduty.com/docs/rulesets). ## Schedules A Schedule determines the time periods that [Users](#users) are [On-Call.](#on-calls) Only [On-Call](#on-calls) [Users](#users) are eligible to receive [Notifications](#notifications) from [Incidents](#incidents). The details of the On-Call Schedule specify which single [User](#users) is [On-Call](#on-calls) for that Schedule at any given point in time. Schedules are used by [Escalation Policies](#escalation-policies) as an escalation target for a given [Escalation Rule](#escalation-rules). [*Read more about Schedules in the PagerDuty Knowledge Base*](/incident-management/schedules/schedule-basics). ### V2 Layer-Based (Legacy Schedule) A V2 Schedule consists of one or more [Schedule Layers](/incident-management/schedules/schedule-basics#schedule-layers) that rotate a group of [Users](#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](https://www.pagerduty.com/early-access/), and contact your Customer Success Manager to confirm your enrollment. #### Rotations A Rotation is a container within a [Flexible Schedule](#v3-shift-based-flexible-schedule) that defines distinct configuration rules [Events](#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](#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](#rotations). 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](#incidents) that associates them with [Escalation Policies](#escalation-policies). A Service is the focal point for [Incident](#incidents) management; Services specify the configuration for the behavior of [Incidents](#incidents) triggered on them. This behavior includes specifying urgency and performing automated actions based on time of day, [Incident](#incidents) duration, and other factors. [*Read more about Services in the PagerDuty Knowledge Base*](/incident-management/services/services-and-integrations). ### 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](#incidents). Integrations feed events into Services and provide event management functionality such as filtering and de-duplication. ## Tags A Tag can be assigned to Escalation Policy, Team or User, and searches for those objects can be filtered to retrieve those with specific tags. ## Teams A Team is a collection of [Users](#users) and [Escalation Policies](#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. [*Read more about Teams in the PagerDuty Knowledge Base*](/account-admin/teams). ## Users Users are members of an Account that have the ability to interact with [Incidents](#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.](#incidents) - Configure [Services](#services), [Escalation Policies](#escalation-policies), [Integrations](#integrations), [On-Call Schedules](#schedules), [Teams](#teams), and more. - Go [On-Call](#on-calls) for one or more [Schedules](#schedules) or [Escalation Policies.](#escalation-policies) - Get [Alerted](#alerts) and receive [Notifications.](#notifications) Depending on a User's role, they may have access to different parts of the account's data. [*Read more about Users in the PagerDuty Knowledge Base*](/account-admin/manage-users). ## Vendors A Vendor represents a specific type of [Integration](#integrations). AWS CloudWatch, Slack, Datadog, are all examples of Vendors that can be integrated into PagerDuty by making an [Integration](/developer/api/reference/rest/services/get-service-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](https://support.pagerduty.com/docs/aws-cloudwatch-integration-guide) on the PagerDuty support site. ## Webhooks Webhook Subscriptions are used to manage the next generation of PagerDuty webhooks: [V3 Webhooks](/developer/webhooks-overview). A Webhook Subscription indicates an interest in a set of [outbound events](/developer/webhooks-overview#event-types) 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). [*Read more about Webhook Subscriptions in the Webhooks v3 Developer Documentation*](/developer/webhooks-overview) ## 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.