openapi: 3.2.0 info: title: Work Analytics Queue Agent Activity 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: Queue Agent Activity paths: /v2/pbxes/{pbxId}/queue-agent-activity: get: tags: - Queue Agent Activity summary: Get Agent Activity Metrics per Queues description: This endpoint returns the agent activity metrics for the selected pbx, grouped by queue and agent. The response can be further filtered by a list of queues, sites, agents, user or queue statuses. If no date range is provided, the metrics reflect the agent activity in the last 24 hours. operationId: get-agent-queue-activity 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. If not passed, all queues data for the given pbx will be returned. required: false schema: type: string - name: userIds in: query description: User ids filtering. Multiple values can be passed separated by comma. required: false schema: type: string - name: userStatuses in: query description: User statuses filtering. Multiple values can be passed separated by comma. required: false schema: type: string enum: - AVAILABLE - BUSY - DND - AWAY - AUTO_AWAY - OFFLINE - ON_CALL - INVISIBLE - name: queueStatuses in: query description: Queue statuses filtering. Multiple values can be passed separated by comma. required: false schema: type: string enum: - AVAILABLE_IDLE - HANDLING - ALERTING - PAUSE - WRAP_UP - BUSY_OTHER - DND - LOGGED_OUT - 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 end 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** | Name | Description | |---------------------------------------|-------------------------------------------------------------------------------------------------------------------------------------------------| | missedInteractions | The number of interactions that were missed by the user. | | rejectedInteractions | The number of interactions that were rejected by the user. | | ongoingTalkingInteractions | The number of interactions that are currently in the talking phase. | | rejectedInteractionsPercentage | The percentage of interactions that were rejected by the user. | | averageOnHoldInteractionsTime | The average time that interactions were on hold. | | ongoingOnHoldInteractions | The number of interactions that are currently on hold. | | userStatusTime | The total time the user has been in their current status. | | missedInteractionsPercentage | The percentage of interactions that were missed by the user. | | ongoingWrapUpInteractionsTime | The time spent on interactions that are currently in the wrap-up phase. | | ongoingAvgTalkingInteractionsTime | The average time spent on interactions that are currently in the talking phase. | | enteredInteractions | The number of interactions that the user has entered into. | | ongoingTotalHandlingInteractionsTime | The total time spent on interactions that are currently being handled. | | acceptedInteractionsPercentage | The percentage of interactions that were accepted by the user. | | averageTalkingInteractionsTime | The average time spent on interactions during the talking phase. | | totalInteractionTime | The total time spent on all interactions. | | ongoingHandlingInteractions | The number of interactions that are currently being handled by the user. | | queueStatusTime | The total time the user has been in the queue status. | | ongoingWrapUpInteractions | The number of interactions that are currently in the wrap-up phase. | | ongoingAvgHandlingInteractionsTime | The average time spent on interactions that are currently being handled. | | ongoingOnHoldInteractionsTime | The time spent on interactions that are currently on hold. | | ongoingTalkingInteractionsTime | The time spent on interactions that are currently in the talking phase. | | averageWrapUpTime | The average time spent on interactions during the wrap-up phase. | | acceptedInteractions | The number of interactions that were accepted by the user. | | agentAverageTimeToAnswer | The average time the agent takes to answer interactions in the queue after alerting begins (alerting duration). Returns null when the agent answered no interactions in the selected period. | ' required: false schema: type: string - name: includeSummary in: query description: If true, the response will contain the summary of agent activity metrics for each queue, otherwise not. required: false schema: type: boolean default: true responses: '200': description: Success content: application/json: schema: $ref: '#/components/schemas/QueueAgentActivityResponse' examples: All Metrics: description: example request value: queuesAgentActivity: - pbx: testPbx site: Test Site queueExtension: '6509967' queueId: X10000 queueName: Timoth autoLogin: false queueAgentActivity: - userId: user_1 agentExtension: '2062112' agentName: John Doe queueStatus: HANDLING userStatus: ON_CALL overflowAgent: false interaction: caller: Caller address: CallerPhone metrics: ongoingHandlingInteractions: 1 acceptedInteractions: 0 ongoingOnHoldInteractionsTime: 0 ongoingTalkingInteractions: 1 ongoingWrapUpInteractionsTime: 0 rejectedInteractions: 0 userStatusTime: 2579000 averageWrapUpTime: 0 ongoingWrapUpInteractions: 0 enteredInteractions: 0 ongoingTalkingInteractionsTime: 2594778 ongoingHandlingInteractionsTime: 2579000 totalInteractionTime: 0 ongoingOnHoldInteractions: 0 queueStatusTime: 2579000 - userId: user_2 agentExtension: '5368894' agentName: Jane Doe queueStatus: ALERTING userStatus: AVAILABLE overflowAgent: false interaction: caller: Another Caller address: AnotherCallerPhone metrics: ongoingHandlingInteractions: 1 acceptedInteractions: 0 ongoingOnHoldInteractionsTime: 2599778 ongoingTalkingInteractions: 0 ongoingWrapUpInteractionsTime: 0 rejectedInteractions: 0 userStatusTime: 2615000 averageWrapUpTime: 0 ongoingWrapUpInteractions: 0 enteredInteractions: 0 ongoingTalkingInteractionsTime: 0 ongoingHandlingInteractionsTime: 2615000 totalInteractionTime: 0 ongoingOnHoldInteractions: 1 queueStatusTime: 2615000 metricsSummary: ongoingHandlingInteractions: 2 acceptedInteractions: 0 ongoingOnHoldInteractionsTime: 2599778 ongoingTalkingInteractions: 1 ongoingWrapUpInteractionsTime: 0 rejectedInteractions: 0 averageWrapUpTime: 0 ongoingWrapUpInteractions: 0 enteredInteractions: 0 ongoingTalkingInteractionsTime: 2594778 ongoingHandlingInteractionsTime: 5195000 totalInteractionTime: 0 ongoingOnHoldInteractions: 1 '400': description: Bad Request content: application/json: schema: $ref: '#/components/schemas/ErrorResponse' examples: Invalid metrics passed: description: Invalid metrics passed value: timestamp: 2023-01-05T12:04:59.100+0000 status: 400 messages: - Invalid Metrics Passed [random,notSupported]. path: /analytics/work/v2/pbxes/PBX_ID_VALUE/queue-agent-activity '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/queue-agent-activity '404': description: Not Found '500': description: Internal Server Error content: application/json: schema: $ref: '#/components/schemas/ErrorResponse' components: schemas: Interaction: type: object properties: caller: type: string address: type: string QueueActivity: type: object properties: pbx: type: string description: The PBX (Private Branch Exchange) identifier associated with the queue. site: type: string description: The site or location where the queue is based. queueId: type: string description: Unique identifier for the queue. queueExtension: type: string description: The phone extension associated with the queue. queueName: type: string description: The name of the queue. autoLogin: type: boolean description: Indicates if agents are automatically logged into the queue. queueAgentActivity: type: array items: $ref: '#/components/schemas/QueueAgentActivity' description: A list of agent activities within the queue. summary: type: object additionalProperties: type: object description: A summary of various metrics and statistics related to the queue's performance. QueueAgentActivity: type: object properties: userId: type: string description: Unique identifier for the agent. agentExtension: type: string description: The phone extension associated with the agent. agentName: type: string description: The name of the agent. queueStatus: type: string description: The current status of the agent within the queue (e.g., AVAILABLE_IDLE, BUSY). userStatus: type: string description: The overall status of the agent (e.g., OFFLINE, AVAILABLE). overflowAgent: type: boolean description: Indicates if the agent is an overflow agent for the queue. interaction: $ref: '#/components/schemas/Interaction' metrics: type: object additionalProperties: type: object description: A collection of various metrics related to the agent's performance within the queue. 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 QueueAgentActivityResponse: type: object properties: queuesAgentActivity: type: array items: $ref: '#/components/schemas/QueueActivity' description: A list of queue activities, including details of each queue and associated agent activities. 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