GET - Get an agent's online status audit

Purpose

Use this API to fetch the status details of an agent during a given time period.

Note

This API will query details for the agent based on the credentials of the querying user.

Authorization

HeaderKey	Description
Authorization*	Zoho-oauthtoken<space><ACCESS_TOKEN>
Accept*	Set to application/json.

Request URL

Method: GET

https://voice.zoho.com/rest/json/zv/metrics/statusaudit/list

Scope: ZohoVoice.agents.READ

Parameters:

Param Name	Data Type	Description
from	Number	Represents the starting index for retrieving records.
size	Number	Represents the number of records to be returned.
fromEpoch*	Long	Represents the start timestamp in epoch milliseconds.
toEpoch*	Long	Represents the end timestamp in epoch milliseconds.
agentIds*	String	Represents single or multiple agent IDs separated by commas.
sortField	String	Represents the status by which the results are sorted. Possible values: On Call Offline On Break Available Busy Working Time
sortMetric	String	Represents the metric by which the results are sorted. Possible values: avg sum min max
sortOrder	String	Represents the sort order. Possible values: asc desc
tz*	String	Represents the timezone used to display the results.
excludeDays	String	Represents the list of weekdays to exclude, where 1 denotes Monday and 7 denotes Sunday, without any separator. Example: To exclude weekends, use 67
excludeStatus	String	Represents the list of statuses to exclude, separated by commas. Example: To exclude Offline and On Break, use On Break,Offline

Sample Request

Copiedcurl "https://voice.zoho.com/rest/json/zv/metrics/statusaudit/list?fromEpoch=1764547200000&toEpoch=1764633600&agentIds=3029000000002015&tz=GMT" \

Sample Response - Success

Copied{
   "code": "200",
   "list": {
       "agentStatus": [
           {
               "previousResult": {
                   "agent_id": "3029000000002015",
                   "previous_action_time": 1728976200110,
                   "agentEmail": "janice@zylker.com",
                   "current_action_time": 1728977814592,
                   "agentName": "Jan",
                   "triggered_by_username": "Jan",
                   "triggered_by": "User",
                   "duration": 1614482,
                   "triggered_by_medium": "Web",
                   "triggered_by_zuid": "67560001",
                   "current_status": "Available",
                   "zsoid": "67560292",
                   "triggered_reason": "",
                   "previous_status": "Offline"
               },
               "agent_id": "3029000000002015",
               "agentEmail": "janice@zylker.com",
               "agentName": "Jan",
               "dates": [
                   {
                       "hits": [
                           {
                               "agent_id": "3029000000002015",
                               "previous_action_time": 1728977814592,
                               "agentEmail": "janice@zylker.com",
                               "triggered_reason_desc": "Automatic Check In",
                               "current_action_time": 1729056300109,
                               "agentName": "Jan",
                               "triggered_by": "Zoho Voice",
                               "duration": 78485517,
                               "triggered_by_medium": "",
                               "triggered_by_zuid": "",
                               "current_status": "Available",
                               "logid": "6prJk5IB_xciauz1XOy0",
                               "zsoid": "67560292",
                               "triggered_reason": "Agent Schedule",
                               "previous_status": "Available"
                           },
                           {
                               "agent_id": "3029000000002015",
                               "previous_action_time": 1729056300109,
                               "agentEmail": "janice@zylker.com",
                               "current_action_time": 1729061808945,
                               "agentName": "Jan",
                               "triggered_by_username": "Jan",
                               "triggered_by": "User",
                               "duration": 5508836,
                               "triggered_by_medium": "Web",
                               "triggered_by_zuid": "67560001",
                               "current_status": "Offline",
                               "logid": "b6MdlJIBm7rVk3YNaz3l",
                               "zsoid": "67560292",
                               "triggered_reason": "",
                               "previous_status": "Available"
                           },
                           ...
                       ],
                       "start_timestamp": 1729036800000,
                       "index": 0
                   },
                   { "hits": [...], "start_timestamp": 1729123200000, "index": 1 },
                   { "hits": [...],"start_timestamp": 1729209600000,"index": 2 },
                   { "hits": [...],"start_timestamp": 1729296000000,"index": 3 },
                   { "hits": [...],"start_timestamp": 1729382400000,"index": 4 },
                   { "hits": [...],"start_timestamp": 1729468800000,"index": 5 },
                   { "hits": [...],"start_timestamp": 1729555200000,"index": 6 }
               ]
           }
       ]
   },
   "status": "SUCCESS"
}

Sample Response - Error

Copied{
 "status": "ERROR",
 "code":"ZVTSA002",
 "response":{
     "errorCode": "ZVTSA003",
     "errorDisplay": "This data cannot be displayed. (You do not have permission to view this queue, or it might no longer exist)",
     "errorMessage": "Unable to display data."
  }
}