The Agent Events API provides access to agent-related updates across your Zendesk Chat account.

This API is currently in limited availability.

JSON format

Incremental Agent Events are represented as JSON objects with the following properties:

account_idintegertruefalseThe agent’s account id
agent_idintegertruefalseThe agent’s unique identifier
field_namestringtruefalseThe agent attribute that changed on this event. Possible values are "status" or "engagements".
idstringtruefalseThe event's unique identifier
previous_valuetruefalseThe value of the attribute before the change. For a status change, possible values are "offline", "online", "away" or "invisible". For an engagements change, the value is the number of concurrent chats (engagements) that the agent was involved in.
timestampstringtruefalseThe date and time in seconds when the event happened
valuetruefalseThe value of the attribute after the change. It can be either a string or an integer. Possible values are the same as previous_value.


{  "account_id": 2,  "agent_id": 980824,  "field_name": "status",  "id": "R6vTSXc.agent:980824.WEuQDQ",  "previous_value": "online",  "timestamp": "2018-10-19T12:33:50.140101Z",  "value": "away"}

Incremental Agent Events Export

  • GET /api/v2/incremental/agent_events

Returns an agent_events object that consists of a chronologically ordered list of any agent-related update generated since the given start time. An event captures:

  • Either any agent status change,
  • Or a change in the number of any agent’s engagements.

Common Response Properties

See the Incremental Exports documentation.

Allowed for

  • Administrator

Resource Expansion

Not applicable.


fieldsstringQueryfalseResponse properties required. See Resource expansion
limitintegerQueryfalseThe number of results to be returned. Default and max 1000
start_idstringQueryfalseDefaults to empty string
start_timeintegerQueryfalseA Unix epoch time in microseconds. See Start time. Defaults to 0

Code Samples

curl "" \  -v -H "Authorization: Bearer {token}"
import (	"fmt"	"io"	"net/http")
func main() {	url := ""	method := "GET"	req, err := http.NewRequest(method, url, nil)
	if err != nil {		fmt.Println(err)		return	}	req.Header.Add("Content-Type", "application/json")
	client := &http.Client {}	res, err := client.Do(req)	if err != nil {		fmt.Println(err)		return	}	defer res.Body.Close()
	body, err := io.ReadAll(res.Body)	if err != nil {		fmt.Println(err)		return	}	fmt.Println(string(body))}
import com.squareup.okhttp.*;OkHttpClient client = new OkHttpClient();HttpUrl.Builder urlBuilder = HttpUrl.parse("")		.newBuilder()		.addQueryParameter("fields", "")		.addQueryParameter("limit", "")		.addQueryParameter("start_id", "")		.addQueryParameter("start_time", "");
Request request = new Request.Builder()		.url(		.method("GET", null)		.addHeader("Content-Type", "application/json")		.build();Response response = client.newCall(request).execute();
var axios = require('axios');
var config = {  method: 'GET',  url: '',  headers: {	'Content-Type': 'application/json',  },  params: {    'fields': '',    'limit': '',    'start_id': '',    'start_time': '',  },};
axios(config).then(function (response) {  console.log(JSON.stringify(;}).catch(function (error) {  console.log(error);});
import requests
url = ""headers = {	"Content-Type": "application/json",}
response = requests.request(	"GET",	url,	headers=headers)
require "net/http"uri = URI("")uri.query = URI.encode_www_form("fields": "", "limit": "", "start_id": "", "start_time": "")request =, "Content-Type": "application/json")response = Net::HTTP.start uri.hostname, uri.port, use_ssl: true do |http|	http.request(request)end

Example response(s)

200 OK
// Status 200 OK
{  "agent_events": [    {      "account_id": 2,      "agent_id": 980824,      "field_name": "status",      "id": "R6vTSXc.agent:980824.WEuQDQ",      "previous_value": "online",      "timestamp": "2018-10-19T12:33:50.140101Z",      "value": "away"    },    {      "account_id": 2,      "agent_id": 980824,      "field_name": "engagements",      "id": "R6vTXhl.agent:980824.y7Q4aI",      "previous_value": 0,      "timestamp": "2018-10-19T12:34:09.989524Z",      "value": 1    },    {      "account_id": 2,      "agent_id": 980824,      "field_name": "engagements",      "id": "R6vTZ0i.agent:980824.wpOTDT",      "previous_value": 1,      "timestamp": "2018-10-19T12:34:15.008359Z",      "value": 0    }  ],  "count": 3,  "end_id": "R7AfRxf.agent:980824.72oQk1",  "end_time": 1540176932.8872,  "next_page": ""}