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:

Name Type Read-only Mandatory Description
account_id integer true false The agent’s account id
agent_id integer true false The agent’s unique identifier
field_name string true false The agent attribute that changed on this event. Possible values are "status" or "engagements".
id string true false The event's unique identifier
previous_value true false The 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.
timestamp string true false The date and time in seconds when the event happened
value true false The 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.


Name Type In Required Description
fields string Query false Response properties required. See Resource expansion
limit integer Query false The number of results to be returned. Default and max 1000
start_id string Query false Defaults to empty string
start_time integer Query false A Unix epoch time in microseconds. See Start time. Defaults to 0

Code Samples

curl "" \  -v -u {email_address}:{password}
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": ""}