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.
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.
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