8x8 Call Queue Metrics API

openapi: 3.2.0
info:
  title: Work Analytics Call Queue Metrics API
  version: 8-x-8-Latest
  description: "The Work Analytics API provides metrics related to call queues activity as well as agent activity on queues.\n### **Time filtering**\nIf no time filtering is provided, the returned metrics reflect the agent activity in the last 24 hours. \\\nThe reports can be generated for a specific date range, specified using 'startDate' and 'endDate' parameters, in ISO 8601 format. If a specific intra day time range is desired, the 'intraDayStart' and 'intraDayEnd', in ISO 8601 format, must be used.\n### **Examples:**\n\n  - To obtain a full day report from 1st of May to 5th of May, in UTC, use startDate: 2023-05-01T00:00:00Z and endDate: 2023-05-05T00:00:00Z. \n  - To obtain a report from 1st of May to 5th of May, in a specific time zone, starting from 8 AM to 6 PM, use startDate: 2023-05-01T00:00:00-0700 and endDate: 2023-05-05T00:00:00-07000, intraDayStart: 08:00:00-0700, intraDayEnd: 18:00:00-0700."
servers:
- url: https://api.8x8.com/analytics/work/
security:
- 8x8-apikey: []
  bearerAuth: []
tags:
- name: Call Queue Metrics
paths:
  /v2/pbxes/{pbxId}/call-queue-metrics:
    get:
      tags:
      - Call Queue Metrics
      summary: Get Call Queue Metrics
      description: This endpoint returns the call queue metrics, for the selected PBX. The response can be further filtered by a list of queues, sites. If no date range is provided, the metrics reflect the activity on queues in the last 24 hours.
      operationId: get-queue-metrics
      parameters:
      - name: pbxId
        in: path
        description: Id of the PBX.
        required: true
        schema:
          type: string
      - name: siteIds
        in: query
        description: Site ids filtering. Multiple values can be passed separated by comma. If not passed, all sites data for the given pbx will be returned.
        required: false
        schema:
          type: string
        examples:
          Single value:
            description: single valued site id filter
            value: JMwyX0BUTRC9uAnuAz8wfg
          Multiple values:
            description: multivalued site id filter
            value: JMwyX0BUTRC9uAnuAz8wfg,JMwyX0BUTRC9uAnuAz8wfg
      - name: queueIds
        in: query
        description: Call Queue ids filtering. Multiple values can be passed separated by comma.
        required: false
        schema:
          type: string
      - name: startDate
        in: query
        description: Report start date in ISO 8601 standard. If startDate is entered, endDate is required as well.
        required: false
        schema:
          type: string
        examples:
          Start date in U.S. Pacific Time time zone:
            description: 2023-06-14 start date in U.S. Pacific Time time zone
            value: 2023-06-14T00:00:00-0700
          Start date in UTC:
            description: 2023-06-14 start date in UTC
            value: '2023-06-14T00:00:00Z'
      - name: endDate
        in: query
        description: Report start date in ISO 8601 standard. If endDate is entered, startDate is required as well.
        required: false
        schema:
          type: string
        examples:
          End date in U.S. Pacific Time time zone:
            description: 2023-06-15 end date in U.S. Pacific Time time zone
            value: 2023-06-15T00:00:00-0700
          End date in UTC:
            description: 2023-06-15 end date in UTC
            value: '2023-06-15T00:00:00Z'
      - name: intraDayStart
        in: query
        description: Report intra day start time (up to seconds) in ISO 8601 standard. If intraDayStart is entered, intraDayEnd is required as well. Report intraDayStart/intraDayEnd parameters should be passed only when report startDate/endDate are passed as well.
        required: false
        schema:
          type: string
        examples:
          intra day start time in U.S. Pacific Time time zone:
            description: 8 AM in U.S. Pacific Time time zone
            value: 08:00:00-0700
          intra day start time in UTC:
            description: 8 AM in UTC
            value: 08:00:00Z
      - name: intraDayEnd
        in: query
        description: Report intra day end time (up to seconds) in ISO 8601 standard. If intraDayEnd is entered, intraDayStart is required as well. Report intraDayStart/intraDayEnd parameters should be passed only when report startDate/endDate are passed as well.
        required: false
        schema:
          type: string
        examples:
          intra day end time in U.S. Pacific Time time zone:
            description: 6 PM in U.S. Pacific Time time zone
            value: 18:00:00-0700
          intra day end time in UTC:
            description: 6 PM in UTC
            value: 18:00:00Z
      - name: metrics
        in: query
        description: 'Expected metrics in response. Multiple values can be passed separated by comma.


          **Values allowed and their description**


          | Metric | Description |

          | ---------------- | ------------|

          | abandonedInWaitingCalls | The total number of waiting interactions that ended up as being hung up by the customer |

          | abandonedInWaitingCallsPercentage | The total number of waiting calls that ended up as being hung up by the customer over the number of entered calls |

          | acceptedCalls | The total number of interactions answered by agents in the queue |

          | acceptedCallsPercentage | The total number of calls answered over the number of entered calls |

          | activeCalls | The number of calls still active at the end of the selected interval |

          | averageAnswerTime | Average time taken to answer a call after ringing begins |

          | averageHandlingTime | Average handling time for interactions in the specified time frame |

          | averageOnHoldTime | Average on hold time for finished calls |

          | averageTalkTime | Average talk time in the specified time frame |

          | averageTimeToAnswer | The average time agents take to answer calls (alerting duration) |

          | averageWaitingTime | Average waiting time for interactions in the specified time frame |

          | completedCalls | The number of calls completed at the end of the selected interval |

          | diverted | The total number of unique inbound calls that entered the queue and were routed to another destination by the system — such as voicemail, another queue, a ring group, or an external number — without ever being offered to any agent. The call never rang at any agent''s device.<br><br>This metric helps distinguish between calls lost due to agent behavior (Missed, Rejected) and calls the system routed away before any agent was involved, which typically indicates a capacity, staffing, or routing configuration issue.<br><br>This metric is calculated after calls are completed, so ongoing calls are not included until they end. |

          | divertedCallsPercentage | The percentage of queue entries that were diverted by the system without ever being offered to an agent. Calculated as: (Diverted ÷ Queue Entries) × 100. If Queue Entries = 0, the value is 0%. |

          | enteredCalls | The total number of interactions that entered the queue |

          | forwardedToVoiceMail | The total number of interactions that were forwarded to voice mail |

          | longestHandlingTime | Longest handling time for interactions in the specified time frame |

          | longestOnHoldTime | Longest on hold time for finished calls |

          | longestTalkTime | Longest talk time in the specified time frame |

          | longestWaitingTime | Longest waiting time for interactions in the specified time frame |

          | ongoingAvailableAgents | Number of users assigned to the queue, logged in and in the Available status |

          | ongoingAvgHandlingTime | Average handling time |

          | ongoingAvgTalkingTime | Average talking time |

          | ongoingAvgWaitingTime | Average waiting time |

          | ongoingEligibleAgents | The number of primary and secondary users in the statuses: Available, Busy, Away, Appear Offline |

          | ongoingEligibleOverflowAgents | The number of secondary users in the statuses: Available, Busy, Away, Appear Offline |

          | ongoingEligiblePrimaryAgents | The number of primary users in the statuses: Available, Busy, Away, Appear Offline |

          | ongoingEnabledOverflowAgents | Number of enabled overflow agents |

          | ongoingEnabledPrimaryAgents | Number of enabled primary agents |

          | ongoingHandlingCalls | Handling calls |

          | ongoingLoggedOutAndDndAgents | Number of primary and secondary users in statuses: Offline, Logged out, Dnd |

          | ongoingLoggedOutAndDndOverflowAgents | Number of secondary users in statuses: Offline, Logged out, Dnd |

          | ongoingLongestHandlingTime | Longest handling time |

          | ongoingLongestOnHoldTime | Longest on hold time |

          | ongoingLongestTalkingTime | Longest talking time |

          | ongoingLongestWaitingTime | Longest waiting time |

          | ongoingOnHoldCalls | On hold calls |

          | ongoingOnHoldTime | On hold time |

          | ongoingOverflowAgents | Total number of secondary users assigned to the queue regardless of their available status |

          | ongoingOverflowWrappingUpAgents | The number of secondary users in Wrap-up state |

          | ongoingPrimaryWrappingUpAgents | The number of primary users in Wrap-up state |

          | ongoingTalkingCalls | Talking calls |

          | ongoingTalkingTime | Talking time |

          | ongoingTotalCalls | Total calls |

          | ongoingTotalHandlingTime | Total handling time |

          | ongoingWaitingCalls | Waiting calls |

          | ongoingWaitingTime | Waiting time |

          | ongoingWrappingUpAgents | The number of primary and secondary users in Wrap-up state |

          | totalHandlingTime | Total handling time for interactions in the specified time frame |

          | totalOnHoldTime | Total on hold time for interactions in the specified time frame |

          | totalTalkTime | Total talk time for calls in the specified time frame |

          | totalWaitingTime | Total waiting time for interactions in the specified time frame |

          | transferredToCallQueue | The total number of interactions that were transferred to a call queue |

          | transferredToCallQueuePercentage | The total number of calls that were transferred to a call queue over the number of entered calls |

          | transferredToExternalNumber | The total number of interactions that were transferred to an external number |

          | transferredToRingGroup | The total number of interactions that were transferred to a ring group |

          | transferredToRingGroupPercentage | The total number of calls that were transferred to a ring group over the number of entered calls |

          '
        required: false
        schema:
          type: string
      - name: includeSummary
        in: query
        description: If true, response will contain the metrics summary for the requested queues, otherwise not.
        required: false
        schema:
          type: boolean
          default: true
      responses:
        '200':
          description: OK
          content:
            application/json:
              schema:
                $ref: '#/components/schemas/QueueMetricsResponse'
              example:
                callQueues:
                - pbx: voaromaniaqe14051
                  site: SanJose-Onel
                  id: tqteLkZOScyi0Mai9ewUlA
                  name: CQ3 (autologin)
                  extension: 1000
                  metrics:
                    ongoingAvgTalkingTime: 0
                    averageTalkTime: 0
                    ongoingEligibleAgents: 1
                    ongoingTotalHandlingTime: 0
                    ongoingTalkingTime: 0
                    ongoingOnHoldTime: 0
                    ongoingEnabledOverflowAgents: 0
                    ongoingLoggedOutAndDndAgents: 1
                    averageWaitingTime: 0
                    forwardedToVoiceMail: 0
                    ongoingTotalAgents: 1
                    ongoingWrappingUpAgents: 0
                    ongoingWaitingCalls: 0
                    enteredCalls: 0
                    ongoingOverflowAgents: 1
                    activeCalls: 0
                    ongoingLoggedOutAndDndOverflowAgents: 1
                    transferredToCallQueue: 0
                    totalWaitingTime: 0
                    averageHandlingTime: 0
                    ongoingLongestHandlingTime: 0
                    ongoingTalkingCalls: 0
                    ongoingEnabledPrimaryAgents: 0
                    longestHandlingTime: 0
                    transferredToExternalNumber: 0
                    missedCalls: 0
                    transferredToRingGroup: 0
                    ongoingEligibleOverflowAgents: 1
                    abandonedInWaitingCallsPercentage: 0
                    ongoingOnHoldCalls: 0
                    ongoingHandlingCalls: 0
                    totalTalkTime: 0
                    ongoingWaitingTime: 0
                    ongoingTotalCalls: 0
                    averageOnHoldTime: 0
                    totalOnHoldTime: 0
                    totalHandlingTime: 0
                    completedCalls: 0
                    diverted: 0
                    divertedCallsPercentage: 0
                    abandonedInWaitingCalls: 0
                    missedCallsPercentage: 0
                    ongoingOverflowWrappingUpAgents: 0
                    ongoingEligiblePrimaryAgents: 0
                    ongoingLongestTalkingTime: 0
                    ongoingLongestWaitingTime: 0
                    longestOnHoldTime: 0
                    longestWaitingTime: 0
                    longestTalkTime: 0
                    ongoingPrimaryWrappingUpAgents: 0
                    ongoingAvgWaitingTime: 0
                    ongoingAvgHandlingTime: 0
                    ongoingAvailableAgents: 0
                    acceptedCalls: 0
                    ongoingLongestOnHoldTime: 0
                - pbx: voaromaniaqe14051
                  site: SanJose-Onel
                  id: ZPSyi0RkSiSISsNSuiYG7w
                  name: CQ4
                  extension: 1013
                  metrics:
                    ongoingAvgTalkingTime: 0
                    averageTalkTime: 0
                    ongoingEligibleAgents: 1
                    ongoingTotalHandlingTime: 0
                    ongoingTalkingTime: 0
                    ongoingOnHoldTime: 0
                    ongoingEnabledOverflowAgents: 0
                    ongoingLoggedOutAndDndAgents: 1
                    averageWaitingTime: 0
                    forwardedToVoiceMail: 0
                    ongoingTotalAgents: 1
                    ongoingWrappingUpAgents: 0
                    ongoingWaitingCalls: 0
                    enteredCalls: 0
                    ongoingOverflowAgents: 1
                    activeCalls: 0
                    ongoingLoggedOutAndDndOverflowAgents: 1
                    transferredToCallQueue: 0
                    totalWaitingTime: 0
                    averageHandlingTime: 0
                    ongoingLongestHandlingTime: 0
                    ongoingTalkingCalls: 0
                    ongoingEnabledPrimaryAgents: 0
                    longestHandlingTime: 0
                    transferredToExternalNumber: 0
                    missedCalls: 0
                    transferredToRingGroup: 0
                    diverted: 0
                    divertedCallsPercentage: 0
        '401':
          description: Unauthorized
          content:
            application/json:
              schema:
                $ref: '#/components/schemas/401ErrorResponse'
        '403':
          description: Forbidden
          content:
            application/json:
              schema:
                $ref: '#/components/schemas/ErrorResponse'
              examples:
                User Not Authorized:
                  description: User Not Authorized
                  value:
                    timestamp: 2023-01-05T12:04:59.100+0000
                    status: 403
                    messages:
                    - user [user_name] does not have access to pbxId [PBX_ID] to make this request.
                    path: /analytics/work/v2/pbxes/PBX_ID_VALUE/call-queue-metrics
        '404':
          description: Not Found
components:
  schemas:
    QueueMetrics:
      type: object
      properties:
        pbx:
          type: string
          description: Identifier for the Private Branch Exchange (PBX) system
        id:
          type: string
          description: The id of the queue
        site:
          type: string
          description: Identifier for the site or location
        name:
          type: string
          description: Name of the queue
        autoLogin:
          type: boolean
          description: If the queue is autologin or not
        extension:
          type: string
          description: Extension number associated with the queue
        metrics:
          type: object
          additionalProperties:
            type: object
    ErrorResponse:
      type: object
      description: Error response
      properties:
        timestamp:
          type: string
          description: Timestamp of the error
          format: date-time
          example: 2023-01-05T12:04:59.100+0000
        status:
          type: integer
          description: HTTP status of the response
          format: int32
        messages:
          type: array
          description: List of business service error messages
          items:
            type: string
        path:
          type: string
          description: Request path
    QueueMetricsResponse:
      type: object
      properties:
        callQueues:
          type: array
          items:
            $ref: '#/components/schemas/QueueMetrics'
        metricsSummary:
          type: object
          additionalProperties:
            type: object
    401ErrorResponse:
      type: object
      description: Error response
      properties:
        error:
          type: string
          description: type of  error
          example: invalid_token
        error_description:
          type: string
          description: Description of the error
          example: 'Access token expired: eyJhbGciOiJSUzI1NiIsInR5cCI6IkpXVCJ9.'
  securitySchemes:
    8x8-apikey:
      type: apiKey
      in: header
      name: 8x8-apikey
    bearerAuth:
      type: http
      scheme: bearer
      bearerFormat: JWT
x-readme:
  explorer-enabled: true
  proxy-enabled: true