Retrieving agent state statistics

Deprecated API

The Statistics API was deprecated in Spring '20. For information about migrating to the Insights Stats API, see Migrating from V0 Statistics to the Insights Stats API.

You must be authenticated to run this method. For information on authentication, see V0 - Authentication API.

All requests to this API are required to be cached by clients for 12 minutes (720 seconds) using the Cache-Control header.

Request Scheme

HTTPS

Request Uri

GET v{v#}/{accountKey}/statistics/agentstates

Request Headers

Authorization (required)

This header requires an OAuth bearer token. For information on the bearer token, see How to use your bearer access token.

Accept (required)

application/json; version=2

Indicates that the media type required from the server is JavaScript Object Notation (JSON). The version parameter is compulsory and you must set it to 2. No other content type is supported.

Parameters

You must provide one of either interval or latest, or both start and end.

start

Defines the start of a range that restricts statistics to a time period. Format is in a specific subset of ISO8601 YYYY-MM-DDThh:mm:ssZ. For example, December 10th 2013 15:00:20 is 2013-12-10T15:00:20Z. You must use the 'Z' suffix to indicate UTC time. The caller must translate local time to UTC. Fractional seconds may be accepted, but sub-second accuracy of filtering should not be expected. The maximum period that you can request in a single call is 25 hours.

end

Defines the start of a range that restricts statistics to a time period. The format matches that required for the start parameter.

interval

Decimal time period (in minutes). Used to retrieve statistics for the past number of minutes. Must be greater than 0 and not
more than 1560 minutes (1 day).

latest

Only supported value is "true". Use this to indicate if you want the past 30 minutes worth of statistics returned

Examples

Most URLs in the example code use the following values:

***. To access the API for your region, replace *** with the correct subdomain for your region:
Region URL subdomain Base URL
EMEA emea https://emea.newvoicemedia.com
USA nam https://nam.newvoicemedia.com
APAC apac https://apac.newvoicemedia.com
a1b2c3d4e5. The value represents the Vonage Contact Center account on which the API request is run. To run the API request on your account data, you must replace a1b2c3d4e5, where used, with your account's API key. For example, if your API key is mtovfiliti3, use mtovfiliti3 in place of a1b2c3d4e5.
<ACCESS_TOKEN>. The value represents a bearer access token which you must use to validate every request. Replace <ACCESS_TOKEN> where used with your bearer access token. For information about getting a bearer access token, see Getting a bearer access token.

All agent state statistics for a specified date range

curl -X GET "https://***.newvoicemedia.com/v0/a1b2c3d4e5/statistics/agentstates?start=2014-02-10T15:00:00Z&end=2014-02-11T07:15:00Z" -H "Authorization: Bearer <ACCESS_TOKEN>" -H "Accept: application/json; version=2"

Returns HTTP status code of 200

All the latest agent state statistics

curl -X GET "https://***.newvoicemedia.com/v0/a1b2c3d4e5/statistics/agentstates?latest=true" -H "Authorization: Bearer <ACCESS_TOKEN>" -H "Accept: application/json; version=2"

Returns HTTP status code of 200

All the agent state statistics for the past 50 minutes

curl -X GET "https://***.newvoicemedia.com/v0/a1b2c3d4e5/statistics/agentstates?interval=50" -H "Authorization: Bearer <ACCESS_TOKEN>" -H "Accept: application/json; version=2"

Returns HTTP status code of 200

Example responses

Returns HTTP status code of 200 and a full JSON representation of agents' states for the specified time period:

HTTP/1.1 200 OK
Cache-Control: must-revalidate, max-age=720, private
Content-Type: application/json; charset=utf-8
Vary: Accept,Authorization

{
  "count":2,
  "stats":[
  {
    "agentId":"10955",
    "groupId":"",
    "stateChangedAt":"2014-02-12T15:06:07Z",
    "state":"Ready",
    "duration":"00:00:09"
  },
  {
    "agentId":"10955",
    "groupId":"44311",
    "stateChangedAt":"2014-02-12T15:06:16Z",
    "state":"Busy Inbound",
    "duration":"00:00:12",
    "callGuid":"0148e4d3-684f-b8b7-e2ba-9014639797f1"

  }]
}

callGuid is only returned for Busy, Call Transferred and Wrap Up (Auto and Manual) agent states.

Example: Invalid requests

Most URLs in the example code use the following values:

***. To access the API for your region, replace *** with the correct subdomain for your region:
Region URL subdomain Base URL
EMEA emea https://emea.newvoicemedia.com
USA nam https://nam.newvoicemedia.com
APAC apac https://apac.newvoicemedia.com
a1b2c3d4e5. The value represents the Vonage Contact Center account on which the API request is run. To run the API request on your account data, you must replace a1b2c3d4e5, where used, with your account's API key. For example, if your API key is mtovfiliti3, use mtovfiliti3 in place of a1b2c3d4e5.
<ACCESS_TOKEN>. The value represents a bearer access token which you must use to validate every request. Replace <ACCESS_TOKEN> where used with your bearer access token. For information about getting a bearer access token, see Getting a bearer access token.

Version not specified

curl -X GET "https://***.newvoicemedia.com/v0/a1b2c3d4e5/statistics/agentstates?interval=9999" -H "Authorization: Bearer <ACCESS_TOKEN>" -H "Accept: application/json"

Returns HTTP status code of 404.

An invalid interval was used

curl -X GET "https://***.newvoicemedia.com/v0/a1b2c3d4e5/statistics/agentstates?interval=9999" -H "Authorization: Bearer <ACCESS_TOKEN>" -H "Accept: application/json; version=2"

Returns HTTP status code of 400, containing a message in a similar format to:

Minute interval supplied exceeds 1 day or is less than 0

An invalid date format was used

curl -X GET "https://***.newvoicemedia.com/v0/a1b2c3d4e5/statistics/agentstates?start=2014-02-10 23:15:00" -H "Authorization: Bearer <ACCESS_TOKEN>" -H "Accept: application/json; version=2"

Returns HTTP status code of 400, containing a message in a similar format to:

{
 "message": "The request is invalid."
}

Response values

Property	Description	Additional information
agentId	The ID of the agent.
groupId	The ID of the group to which the agent belongs.	If the agent does not belong to a group, an empty string will be returned.
stateChangedAt	The date and time of the agent state change.	This is a UTC value presented in the ISO 8601 format YYYY-MM-DDThh:mm:ssZ.
state	The agent's state.	For a full list of possible values, see "Valid agent state values" below.
duration	The time that the agent is in the corresponding state.	This is presented in hh:mm:ss format.
callGuid	The unique identifier (global) of the interaction.	This data will only be included where an interaction is involved, i.e. for Busy, Call Transferred and Wrap Up (Auto and Manual) agent states.

Valid agent state values

The following list shows the valid values for state:

Away
Break
Busy In Return
Busy Inbound
Busy Internal
Busy Out Return
Busy Outbound
Busy Payment IVR
Call Failed IVR
Call Transferred
Caller Hangup IVR
CC
CCA
Comfort Break
Dialling
Extended Away
Fault on Line
In Meeting
Ivr Transfer Error
Line Busy
Logged Out
Lunch
Network Congestion
No Answer
Paperwork
Ready
Ready (Offline)
Ready for Outbound
Team Meeting
Training
Transfer In
UnexpectedProhibitedEmergency
Wrap Up (Auto)
Wrap Up (Manual)

The following values for state are also valid if you have set up custom states:

Custom State 256-271 (custom Wrap Up states)
Custom State 304-319 (custom Away states)
Custom State 320-335 (custom Extended Away states)
Custom State 384-399 (custom Ready for Outbound states)

For information about setting up custom states, see /wiki/spaces/PD/pages/2884021.

Region	URL subdomain	Base URL
EMEA	emea	https://emea.newvoicemedia.com
USA	nam	https://nam.newvoicemedia.com
APAC	apac	https://apac.newvoicemedia.com