PagerDuty Analytics API

openapi: 3.0.2
info:
  description: 'This document describes the PagerDuty REST APIs.


    For guides and examples please visit our [Documentation.](https://developer.pagerduty.com/docs/get-started/getting-started/)


    Our REST APIs are defined in OpenAPI v3.x. You can view the schema at [github.com/PagerDuty/api-schema](https://github.com/PagerDuty/api-schema).


    Note that properties in some schemas have fields not shown by default such as `readOnly`, `format`, and `default`. Hover your cursor over the right column that looks like `optional+1` to see the full list of fields.

    '
  contact:
    name: PagerDuty Support
    url: http://www.pagerduty.com/support
    email: support@pagerduty.com
  title: PagerDuty Abilities Analytics API
  version: 2.0.0
servers:
- url: https://api.pagerduty.com
  description: PagerDuty V2 API.
security:
- api_key: []
tags:
- name: Analytics
  description: 'Provides enriched incident data.

    '
paths:
  /analytics/metrics/incidents/all:
    parameters: []
    post:
      x-pd-requires-scope: analytics.read
      summary: PagerDuty Get aggregated incident data
      operationId: getAnalyticsMetricsIncidentsAll
      responses:
        '200':
          description: OK
          content:
            application/json:
              schema:
                allOf:
                - type: object
                  properties:
                    data:
                      type: array
                      items:
                        title: Analytics Incident Metrics
                        type: object
                        properties:
                          mean_assignment_count:
                            type: integer
                            description: Mean count of instances where responders were assigned an incident (including through reassignment or escalation) or accepted a responder request.
                          mean_engaged_seconds:
                            type: integer
                            description: 'Mean engaged time across all responders.

                              Engaged time is measured from the time a user engages with an incident (by

                              acknowledging or accepting a responder request) until the incident is resolved.

                              This may include periods in which the incidents were snoozed.'
                          mean_engaged_user_count:
                            type: integer
                            description: 'Mean number of users who engaged with an incident. *Engaged* is defined as

                              acknowledging an incident or accepting a responder request in it.'
                          mean_seconds_to_engage:
                            type: integer
                            description: 'A measure of *people response time*. This metric measures the time from

                              the first user engagement (acknowledge or responder accept) to the last.

                              This metric is only used for incidents with **multiple responders**;

                              for incidents with one or no engaged users, this value is null.'
                          mean_seconds_to_first_ack:
                            type: integer
                            description: Mean time between the start of an incident, and the first responder to acknowledge.
                          mean_seconds_to_mobilize:
                            type: integer
                            description: 'Mean time between the start of an incident, and the last additional responder

                              to acknowledge. For incidents with one or no engaged users, this value is null.'
                          mean_seconds_to_resolve:
                            type: integer
                            description: Mean time from when an incident was triggered until it was resolved.
                          mean_user_defined_engaged_seconds:
                            type: integer
                            description: "Mean engaged time across all responders. Engaged time is measured from the time \na user engages with an incident (by acknowledging or accepting a responder request) \nuntil the incident is resolved. This may include periods in which the incidents were snoozed.\nThis metric uses the incident response effort values that \n[users have defined](https://support.pagerduty.com/docs/edit-incidents#edit-incident-duration),\nif they exist."
                          p50_seconds_to_first_ack:
                            type: integer
                            description: Median time between the start of an incident, and the first responder to acknowledge.
                          p50_seconds_to_resolve:
                            type: integer
                            description: Median time from when an incident was triggered until it was resolved.
                          p75_seconds_to_first_ack:
                            type: integer
                            description: 75th percentile for the time between the start of an incident, and the first responder to acknowledge.
                          p75_seconds_to_resolve:
                            type: integer
                            description: 75th percentile for the time when an incident was triggered until it was resolved.
                          p90_seconds_to_first_ack:
                            type: integer
                            description: 90th percentile for the time between the start of an incident, and the first responder to acknowledge.
                          p90_seconds_to_resolve:
                            type: integer
                            description: 90th percentile for the time when an incident was triggered until it was resolved.
                          p95_seconds_to_first_ack:
                            type: integer
                            description: 95th percentile for the time between the start of an incident, and the first responder to acknowledge.
                          p95_seconds_to_resolve:
                            type: integer
                            description: 95th percentile for the time when an incident was triggered until it was resolved.
                          range_start:
                            type: string
                            description: Start of the date range for which the metrics were calculated. Only included when an aggregate unit is specified in the request.
                          service_id:
                            type: string
                            description: ID of the service. Only included when aggregating by service. Not included when aggregating by all.
                          service_name:
                            type: string
                            description: Name of the service. Only included when aggregating by service. Not included when aggregating by all.
                          team_id:
                            type: string
                            description: ID of the team to which the incident was assigned. Not included when aggregating by all.
                          team_name:
                            type: string
                            description: Name of the team to which the incident was assigned. Not included when aggregating by all.
                          total_business_hour_interruptions:
                            type: integer
                            description: Total number of unique interruptions during business hours; 8am-6pm Mon-Fri, based on the user’s time zone.
                          total_engaged_seconds:
                            type: integer
                            description: 'Total engaged time across all responders. Engaged time is measured from

                              the time a user engages with an incident (by acknowledging or accepting a responder request)

                              until the incident is resolved. This may include periods in which the incidents were snoozed.'
                          total_escalation_count:
                            type: integer
                            description: 'Total count of instances where an incident is escalated between responders

                              assigned to an escalation policy.'
                          total_incident_count:
                            type: integer
                            description: The total number of incidents that were created.
                          total_incidents_acknowledged:
                            type: integer
                            description: "The total count of assigned incidents acknowledged. \nOnly explicit incident acknowledgment counts; reassign, resolve, and escalation actions do not imply acknowledgement."
                          total_incidents_auto_resolved:
                            description: "The total count of incidents that were resolved automatically. \nThis count includes incidents resolved via an integration and those that were [auto-resolved in PagerDuty](https://support.pagerduty.com/docs/configurable-service-settings#auto-resolution)."
                          total_incidents_manual_escalated:
                            type: integer
                            description: The total count of incidents that were manually escalated.
                          total_incidents_reassigned:
                            type: integer
                            description: The total count of incidents that were reassigned.
                          total_incidents_timeout_escalated:
                            type: integer
                            description: The total count of incidents that were escalated due to timeouts.
                          total_interruptions:
                            type: integer
                            description: Total number of unique interruptions.
                          total_notifications:
                            type: integer
                            description: The total count of incident notifications sent via email, SMS, phone call and push.
                          total_off_hour_interruptions:
                            type: integer
                            description: Total number of unique interruptions during off hours; 6pm-10pm Mon-Fri and all day Sat-Sun, based on the user’s time zone.
                          total_sleep_hour_interruptions:
                            type: integer
                            description: 'Total number of unique interruptions during sleep hours.

                              Sleep hours: 10pm-8am every day, based on the user’s time zone.'
                          total_snoozed_seconds:
                            type: integer
                            description: Total number of seconds incidents were snoozed.
                          total_user_defined_engaged_seconds:
                            type: integer
                            description: "Total engaged time across all responders. Engaged time is measured from\nthe time a user engages with an incident (by acknowledging or accepting a responder request)\nuntil the incident is resolved. This may include periods in which the incidents were snoozed.\nThis metric uses the edited incident response effort values that \n[users have defined](https://support.pagerduty.com/docs/edit-incidents#edit-incident-duration),\nif they exist."
                          up_time_pct:
                            type: number
                            description: 'The percentage of time in the defined date range that the service was not interrupted

                              by a [major incident](https://support.pagerduty.com/docs/operational-reviews#major-incidents).

                              Only included when aggregating by team, escalation policy, service, or all services.'
                - $ref: '#/components/schemas/AnalyticsModel'
              examples:
                Example Response:
                  value:
                    aggregate_unit: day
                    data:
                    - mean_assignment_count: 1
                      mean_engaged_seconds: 366
                      mean_engaged_user_count: 1
                      mean_seconds_to_engage: 81
                      mean_seconds_to_first_ack: 63
                      mean_seconds_to_mobilize: 41
                      mean_seconds_to_resolve: 380
                      mean_user_defined_engaged_seconds: 366
                      range_start: '2024-01-01T00:00:00'
                      total_business_hour_interruptions: 81
                      total_engaged_seconds: 3591
                      total_escalation_count: 5
                      total_incident_count: 124
                      total_incidents_acknowledged: 0
                      total_incidents_auto_resolved: 0
                      total_incidents_manual_escalated: 0
                      total_incidents_reassigned: 0
                      total_incidents_timeout_escalated: 0
                      total_interruptions: 2
                      total_notifications: 2
                      total_off_hour_interruptions: 20
                      total_sleep_hour_interruptions: 21
                      total_snoozed_seconds: 78
                      total_user_defined_engaged_seconds: 3591
                    filters:
                      create_range_start: '2024-01-01T00:00:00Z'
                      create_range_end: '2024-02-01T00:00:00Z'
                      urgency: high
                      major: true
                      team_ids:
                      - PGVXG6U
                      - PNVU4U4
                      service_ids:
                      - PQVUB8D
                      - PU2D9X3
                    time_zone: Etc/UTC
        '400':
          $ref: '#/components/responses/ArgumentError'
        '429':
          $ref: '#/components/responses/TooManyRequests'
      parameters:
      - $ref: '#/components/parameters/header_Accept'
      - $ref: '#/components/parameters/header_Content-Type'
      requestBody:
        content:
          application/json:
            schema:
              $ref: '#/components/schemas/AnalyticsModel'
            examples:
              Example Request:
                value:
                  filters:
                    created_at_start: '2024-01-01T00:00:00-05:00'
                    created_at_end: '2024-01-31T00:00:00-05:00'
                    urgency: high
                    major: true
                    team_ids:
                    - PGVXG6U
                    - PNVU4U4
                    service_ids:
                    - PQVUB8D
                    - PU2D9X3
                  aggregate_unit: day
                  time_zone: Etc/UTC
        description: Parameters and filters to apply to the dataset.
      description: 'Provides aggregated enriched metrics for incidents.


        The provided metrics are aggregated by day, week, month using the aggregate_unit parameter, or for the entire period if no aggregate_unit is provided.


        <!-- theme: info -->

        > A `team_ids` or `service_ids` filter is required for [user-level API keys](https://support.pagerduty.com/docs/using-the-api#section-generating-a-personal-rest-api-key) or keys generated through an OAuth flow. Account-level API keys do not have this requirement.

        <!-- theme: info -->

        > **Note:** Analytics data is updated once per day. It takes up to 24 hours before new incidents appear in the Analytics API.


        Scoped OAuth requires: `analytics.read`

        '
      tags:
      - Analytics
  /analytics/metrics/incidents/escalation_policies:
    parameters: []
    post:
      x-pd-requires-scope: analytics.read
      summary: PagerDuty Get aggregated escalation policy data
      operationId: getAnalyticsMetricsIncidentsEscalationPolicy
      responses:
        '200':
          description: Only returns data for escalation policies that match the filters and have data.
          content:
            application/json:
              schema:
                allOf:
                - type: object
                  properties:
                    data:
                      type: array
                      items:
                        $ref: '#/components/schemas/AnalyticsIncidentMetricsEscalationPolicy'
                - $ref: '#/components/schemas/AnalyticsModel'
              examples:
                Example Response:
                  value:
                    data:
                    - distinct_responder_count: 1
                      escalation_policy_id: PDESCP1
                      escalation_policy_name: Escalation Policy 1
                      mean_assignment_count: 1
                      mean_engaged_seconds: 81
                      mean_engaged_user_count: 63
                      mean_seconds_to_engage: 41
                      mean_seconds_to_first_ack: 380
                      mean_seconds_to_mobilize: 81
                      mean_seconds_to_resolve: 3591
                      mean_user_defined_engaged_seconds: 81
                      team_id: PDTEAM1
                      team_name: Team 1
                      total_business_hour_interruptions: 5
                      total_engaged_seconds: 124
                      total_escalation_count: 20
                      total_incident_count: 21
                      total_incidents_acknowledged: 78
                      total_incidents_auto_resolved: 3
                      total_incidents_manual_escalated: 3
                      total_incidents_reassigned: 4
                      total_incidents_timeout_escalated: 1
                      total_interruptions: 1
                      total_notifications: 23
                      total_off_hour_interruptions: 3
                      total_sleep_hour_interruptions: 1
                      total_snoozed_seconds: 341
                      total_user_defined_engaged_seconds: 124
                      up_time_pct: 9.124123
                    - distinct_responder_count: 1
                      escalation_policy_id: PDESCP2
                      escalation_policy_name: Escalation Policy 2
                      mean_assignment_count: 1
                      mean_engaged_seconds: 81
                      mean_engaged_user_count: 63
                      mean_seconds_to_engage: 41
                      mean_seconds_to_first_ack: 380
                      mean_seconds_to_mobilize: 81
                      mean_seconds_to_resolve: 3591
                      mean_user_defined_engaged_seconds: 81
                      team_id: PDTEAM1
                      team_name: Team 1
                      total_business_hour_interruptions: 5
                      total_engaged_seconds: 124
                      total_escalation_count: 20
                      total_incident_count: 21
                      total_incidents_acknowledged: 78
                      total_incidents_auto_resolved: 3
                      total_incidents_manual_escalated: 3
                      total_incidents_reassigned: 4
                      total_incidents_timeout_escalated: 1
                      total_interruptions: 1
                      total_notifications: 23
                      total_off_hour_interruptions: 3
                      total_sleep_hour_interruptions: 1
                      total_snoozed_seconds: 341
                      total_user_defined_engaged_seconds: 124
                      up_time_pct: 9.124123
                    filters:
                      created_at_start: '2023-06-10T00:00:00Z'
                      created_at_end: '2023-06-12T00:00:00Z'
                      urgency: high
                      major: true
                      escalation_policy_ids:
                      - PDESCP1
                      - PDESCP2
                    time_zone: Etc/UTC
        '400':
          $ref: '#/components/responses/ArgumentError'
        '429':
          $ref: '#/components/responses/TooManyRequests'
      parameters:
      - $ref: '#/components/parameters/header_Accept'
      - $ref: '#/components/parameters/header_Content-Type'
      requestBody:
        content:
          application/json:
            schema:
              $ref: '#/components/schemas/AnalyticsModel'
            examples:
              Example Request:
                value:
                  filters:
                    created_at_start: '2023-06-10T00:00:00-07:00'
                    created_at_end: '2023-06-11T23:59:59-07:00'
                    urgency: high
                    major: true
                    escalation_policy_ids:
                    - PDESCP1
                    - PDESCP2
                  time_zone: Etc/UTC
        description: Parameters and filters to apply to the dataset.
      description: 'Provides aggregated metrics for incidents aggregated into units of time by escalation policy.


        Example metrics include Seconds to Resolve, Seconds to Engage, Snoozed Seconds, and Sleep Hour Interruptions. Metric definitions can be found in our [Knowledge Base](https://support.pagerduty.com/docs/insights#escalation-policy-list).


        <!-- theme: info -->

        > **Note:** Analytics data is updated once per day. It takes up to 24 hours before new incidents appear in the Analytics API.


        Scoped OAuth requires: `analytics.read`

        '
      tags:
      - Analytics
  /analytics/metrics/incidents/escalation_policies/all:
    parameters: []
    post:
      x-pd-requires-scope: analytics.read
      summary: PagerDuty Get aggregated metrics for all escalation policies
      operationId: getAnalyticsMetricsIncidentsEscalationPolicyAll
      responses:
        '200':
          description: Only returns data for escalation policies that match the filters and have data.
          content:
            application/json:
              schema:
                allOf:
                - type: object
                  properties:
                    data:
                      type: array
                      items:
                        $ref: '#/components/schemas/AnalyticsIncidentMetricsEscalationPolicy'
                - $ref: '#/components/schemas/AnalyticsModel'
              examples:
                Example Response:
                  value:
                    data:
                    - distinct_responder_count: 1
                      mean_assignment_count: 1
                      mean_engaged_seconds: 81
                      mean_engaged_user_count: 63
                      mean_seconds_to_engage: 41
                      mean_seconds_to_first_ack: 380
                      mean_seconds_to_mobilize: 81
                      mean_seconds_to_resolve: 3591
                      mean_user_defined_engaged_seconds: 81
                      total_business_hour_interruptions: 5
                      total_engaged_seconds: 124
                      total_escalation_count: 20
                      total_incident_count: 21
                      total_incidents_acknowledged: 78
                      total_incidents_auto_resolved: 3
                      total_incidents_manual_escalated: 3
                      total_incidents_reassigned: 4
                      total_incidents_timeout_escalated: 1
                      total_interruptions: 1
                      total_notifications: 23
                      total_off_hour_interruptions: 3
                      total_sleep_hour_interruptions: 1
                      total_snoozed_seconds: 341
                      total_user_defined_engaged_seconds: 124
                      up_time_pct: 9.124123
                    filters:
                      created_at_start: '2023-06-17T07:00:00Z'
                      created_at_end: '2023-07-02T06:59:59Z'
                      escalation_policy_ids:
                      - PDESCP1
                      - PDESCP2
                    time_zone: Etc/UTC
        '400':
          $ref: '#/components/responses/ArgumentError'
        '429':
          $ref: '#/components/responses/TooManyRequests'
      parameters:
      - $ref: '#/components/parameters/header_Accept'
      - $ref: '#/components/parameters/header_Content-Type'
      requestBody:
        content:
          application/json:
            schema:
              $ref: '#/components/schemas/AnalyticsModel'
            examples:
              Example Request:
                value:
                  filters:
                    created_at_start: '2023-06-17T00:00:00-07:00'
                    created_at_end: '2023-07-01T23:59:59-07:00'
                    escalation_policy_ids:
                    - PDESCP1
                    - PDESCP2
                  time_zone: Etc/UTC
        description: Parameters and filters to apply to the dataset.
      description: 'Provides aggregated metrics across all escalation policies.


        Example metrics include Seconds to Resolve, Seconds to Engage, Snoozed Seconds, and Sleep Hour Interruptions. Metric definitions can be found in our [Knowledge Base](https://support.pagerduty.com/docs/insights#escalation-policy-list).


        <!-- theme: info -->

        > **Note:** Analytics data is updated once per day. It takes up to 24 hours before new incidents appear in the Analytics API.


        Scoped OAuth requires: `analytics.read`

        '
      tags:
      - Analytics
  /analytics/metrics/incidents/services:
    parameters: []
    post:
      x-pd-requires-scope: analytics.read
      summary: PagerDuty Get aggregated service data
      operationId: getAnalyticsMetricsIncidentsService
      responses:
        '200':
          description: Only returns data for services that match the filters and have data.
          content:
            application/json:
              schema:
                allOf:
                - type: object
                  properties:
                    data:
                      type: array
                      items:
                        $ref: '#/components/schemas/AnalyticsIncidentMetrics'
                - $ref: '#/components/schemas/AnalyticsModel'
              examples:
                Example Response:
                  value:
                    aggregate_unit: day
                    data:
                    - mean_assignment_count: 1
                      mean_engaged_seconds: 366
                      mean_engaged_user_count: 1
                      mean_seconds_to_engage: 81
                      mean_seconds_to_first_ack: 63
                      mean_seconds_to_mobilize: 41
                      mean_seconds_to_resolve: 380
                      mean_user_defined_engaged_seconds: 366
                      range_start: '2023-06-11T00:00:00'
                      service_id: PPSCXAN
                      service_name: Critical Prod Service 1
                      team_id: P3XUQ75
                      team_name: Engineering
                      total_business_hour_interruptions: 81
                      total_engaged_seconds: 3591
                      total_escalation_count: 5
                      total_incident_count: 124
                      total_incidents_acknowledged: 1
                      total_incidents_auto_resolved: 12
                      total_incidents_manual_escalated: 9
                      total_incidents_reassigned: 1
                      total_incidents_timeout_escalated: 4
                      total_interruptions: 1
                      total_notifications: 342
                      total_off_hour_interruptions: 20
                      total_sleep_hour_interruptions: 21
                      total_snoozed_seconds: 78
                      total_user_defined_engaged_seconds: 3591
                      up_time_pct: 99.92677595628416
                    - mean_assignment_count: 12
                      mean_engaged_seconds: 432
                      mean_engaged_user_count: 1
                      mean_seconds_to_engage: 77
                      mean_seconds_to_first_ack: 32
                      mean_seconds_to_mobilize: 32
                      mean_seconds_to_resolve: 87
                      mean_user_defined_engaged_seconds: 432
                      range_start: '2023-06-10T00:00:00'
                      service_id: PPSCXAN
                      service_name: Critical Prod Service 1
                      team_id: P3XUQ75
                      team_name: Engineering
                      total_business_hour_interruptions: 12
                      total_engaged_seconds: 3645
                      total_escalation_count: 5
                      total_incident_count: 124
                      total_incidents_acknowledged: 1
                      total_incidents_auto_resolved: 12
                      total_incidents_manual_escalated: 9
                      total_incidents_reassigned: 1
                      total_incidents_timeout_escalated: 4
                      total_interruptions: 1
                      total_notifications: 32
                      total_off_hour_interruptions: 42
                      total_sleep_hour_interruptions: 3
                      total_snoozed_seconds: 123
                      total_user_defined_engaged_seconds: 3645
                      up_time_pct: 99.234416
                    filters:
                      created_at_start: '2023-06-10T00:00:00Z'
                      created_at_end: '2023-06-12T00:00:00Z'
                      team_ids:
                      - P3XUQ75
                      service_ids:
                      - PPSCXAN
                    time_zone: Etc/UTC
        '400':
          $ref: '#/components/responses/ArgumentError'
        '429':
          $ref: '#/components/responses/TooManyRequests'
      parameters:
      - $ref: '#/components/parameters/header_Accept'
      - $ref: '#/components/parameters/header_Content-Type'
      requestBody:
        content:
          application/json:
            schema:
              $ref: '#/components/schemas/AnalyticsModel'
            examples:
              Example Request:
                value:
                  filters:
                    created_at_start: '2023-06-10T00:00:00-07:00'
                    created_at_end: '2023-06-11T23:59:59-07:00'
                    urgency: high
                    major: true
                    team_ids:
                    - P3XUQ75
                    service_ids:
                    - PPSCXAN
                  aggregate_unit: day
                  time_zone: Etc/UTC
        description: Parameters and filters to apply to the dataset.
      description: 'Provides aggregated metrics for incidents aggregated into units of time by service.


        Example metrics include Seconds to Resolve, Seconds to Engage, Snoozed Seconds, and Sleep Hour Interruptions. Metric definitions can be found in our [Knowledge Base](https://support.pagerduty.com/docs/insights#services-list).

        Data can be aggregated by day, week or month in addition to by service, or provided just as a collection of aggregates for each service in the dataset for the entire period.  If a unit is provided, each row in the returned dataset will include a ''range_start'' timestamp.


        <!-- theme: info -->

        > **Note:** Analytics data is updated once per day. It takes up to 24 hours before new incidents appear in the Analytics API.


        Scoped OAuth requires: `analytics.read`

        '
      tags:
      - Analytics
  /analytics/metrics/incidents/services/all:
    parameters: []
    post:
      x-pd-requires-scope: analytics.read
      summary: PagerDuty Get aggregated metrics for all services
      operationId: getAnalyticsMetricsIncidentsServiceAll
      responses:
        '200':
          description: Only returns data for services that match the filters and have data.
          content:
            application/json:
              schema:
                allOf:
                - type: object
                  properties:
                    data:
                      type: array
                      items:
                        $ref: '#/components/schemas/AnalyticsIncidentMetrics'
                - $ref: '#/components/schemas/AnalyticsModel'
              examples:
                Example Response:
                  value:
                    data:
                    - mean_assignment_count: 1
                      mean_engaged_seconds: 366
                      mean_engaged_user_count: 1
                      mean_seconds_to_engage: 81
                      mean_seconds_to_first_ack: 63
                      mean_seconds_to_mobilize: 41
                      mean_seconds_to

# --- truncated at 32 KB (131 KB total) ---
# Full source: https://raw.githubusercontent.com/api-evangelist/pagerduty/refs/heads/main/openapi/pagerduty-analytics-api-openapi.yml