Task List Events

The Task List Events API lets you retrieve a log of activities that occurred on a task list and its tasks, such as task list creation, task updates, and task completion. To learn more about task lists, see Creating task lists to help agents solve tickets in Zendesk help.

Each event is associated with the task list or a task within the task list. Events include information about the actor who triggered the change. Actors can be human users (admins or agents) or system actors.

Events for individual tasks are returned when listing events for the parent task list. There is no separate endpoint for task-level events.

Permissions

The user submitting a Task List Events API request must be able to view the task list referenced in the request. See the Task Lists API.

Event retention

Task list events are retained for the lifetime of the task list. There is no time-based expiration for these events.

Events are automatically deleted when the task list is deleted.

JSON format

Task List Events are represented as JSON objects with the following properties:

Name	Type	Read-only	Mandatory	Description
actor	object	false	true	The user or system that triggered the event
associated_with	string	false	false	Identifier for the task list or task this event belongs to. Present on task list and task events in the response.
created_at	string	false	true	When the event was created (ISO-8601 format)
description	string	false	false	A description of the event
id	string	false	true	Unique identifier for the event
properties	object	false	true	Event properties containing transaction details
received_at	string	false	true	When the event was received (ISO-8601 format)
source	string	false	true	The source of the event (always "zendesk" for standard events)
type	string	false	true	The event type: "record_created" or "record_updated"

An event associated with a task list or a task within a task list

A task list event describes a change to a task list or a task within a task list.

Name	Type	Read-only	Description
id	string	yes	Unique identifier for the event
type	string	yes	The event type: "record_created" or "record_updated"
source	string	yes	The source of the event (always "zendesk" for standard events)
description	string	yes	A description of the event
actor	object	yes	The user who triggered the event. See actor object
created_at	string	yes	When the event was created (ISO-8601 format)
received_at	string	yes	When the event was received (ISO-8601 format)
properties	object	yes	Event properties containing transaction details. See properties object
associated_with	string	yes	Identifier for the task list or task this event belongs to. Present on task list and task events in the response. Example: "zen:custom_object:standard::task_list_instance:01KFGZJGMQ3NA9DNX34Y5YGGYM"

Actor object

The actor object identifies who triggered the event.

Name	Type	Description
user_id	integer	The id of the user who triggered the event

Properties object

The properties object contains details about what changed.

Name	Type	Description
transactional_events	array	List of changes in this transaction. See transaction event object

Transaction event object

Each transaction event represents a single change to a task list or task property.

Name	Type	Description
type	string	The type of change: "name_changed", "custom_field_changed", or "external_id_changed"
originated_from	object	The source of the change. See originated from object
key	string	Identifies the task list or task attribute that changed (present for "custom_field_changed" events)
previous	string	The previous value
current	string	The new value

The "custom_field_changed" type indicates that a task list or task property was updated. Use the key, previous, and current properties to determine what changed.

Originated from object

Indicates how the change was made.

Name	Type	Description
from_ui	object	Present if the change was made via the UI. Contains ip_address
from_trigger	object	Present if the change was made by a trigger. Contains trigger_id and revision_id
from_api	object	Present if the change was made via API. Contains token_id

List Events for Task List

• GET /api/v2/task_lists/{task_list_id}/events

Returns a paginated log of events for the specified task list, including events for tasks in the task list.

Events capture changes such as task list creation, task updates, and task completion. Events for individual tasks are included in the response when you list events for the parent task list.

Allowed For

• Agents with read access to the task list

Parameters

Name	Type	In	Required	Description
page[after]	string	Query	false	Cursor for pagination. Use the value from links.next in the response.
page[size]	integer	Query	false	Number of events to return per page
task_list_id	string	Path	true	The task list id

Code Samples

curl

curl "https://{subdomain}.zendesk.com/api/v2/task_lists/{task_list_id}/events" \
  -H "Authorization: Bearer {access_token}"

Go

import (
	"fmt"
	"io"
	"net/http"
)

func main() {
	url := "https://support.zendesk.com/api/v2/task_lists//events?page[after]=&page[size]="
	method := "GET"
	req, err := http.NewRequest(method, url, nil)

	if err != nil {
		fmt.Println(err)
		return
	}
	req.Header.Add("Content-Type", "application/json")
	req.Header.Add("Authorization", "Basic <auth-value>") // Base64 encoded "{email_address}/token:{api_token}"

	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))
}

Java

import com.squareup.okhttp.*;
OkHttpClient client = new OkHttpClient();
HttpUrl.Builder urlBuilder = HttpUrl.parse("https://support.zendesk.com/api/v2/task_lists//events")
		.newBuilder()
		.addQueryParameter("page[after]", "")
		.addQueryParameter("page[size]", "");
String userCredentials = "your_email_address" + "/token:" + "your_api_token";
String basicAuth = "Basic " + java.util.Base64.getEncoder().encodeToString(userCredentials.getBytes());

Request request = new Request.Builder()
		.url(urlBuilder.build())
		.method("GET", null)
		.addHeader("Content-Type", "application/json")
		.addHeader("Authorization", basicAuth)
		.build();
Response response = client.newCall(request).execute();

Nodejs

var axios = require('axios');

var config = {
  method: 'GET',
  url: 'https://support.zendesk.com/api/v2/task_lists//events',
  headers: {
	'Content-Type': 'application/json',
	'Authorization': 'Basic <auth-value>', // Base64 encoded "{email_address}/token:{api_token}"
  },
  params: {
    'page[after]': '',
    'page[size]': '',
  },
};

axios(config)
.then(function (response) {
  console.log(JSON.stringify(response.data));
})
.catch(function (error) {
  console.log(error);
});

Python

import requests
from requests.auth import HTTPBasicAuth

url = "https://support.zendesk.com/api/v2/task_lists//events?page[after]=&page[size]="
headers = {
	"Content-Type": "application/json",
}
email_address = 'your_email_address'
api_token = 'your_api_token'
# Use basic authentication
auth = HTTPBasicAuth(f'{email_address}/token', api_token)

response = requests.request(
	"GET",
	url,
	auth=auth,
	headers=headers
)

print(response.text)

Ruby

require "net/http"
require "base64"
uri = URI("https://support.zendesk.com/api/v2/task_lists//events")
uri.query = URI.encode_www_form("page[after]": "", "page[size]": "")
request = Net::HTTP::Get.new(uri, "Content-Type": "application/json")
email = "your_email_address"
api_token = "your_api_token"
credentials = "#{email}/token:#{api_token}"
encoded_credentials = Base64.strict_encode64(credentials)
request["Authorization"] = "Basic #{encoded_credentials}"
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

{
  "events": [
    {
      "actor": {
        "user_id": 4398147187967
      },
      "associated_with": "zen:custom_object:standard::task_list_instance:01KFGZJGMQ3NA9DNX34Y5YGGYM",
      "created_at": "2024-03-06T04:55:45.112Z",
      "description": "",
      "id": "01HR91W56R71K30CHJCSJKGDSJ",
      "properties": {
        "transactional_events": [
          {
            "current": "Verify employee paperwork (updated)",
            "originated_from": {
              "from_ui": {
                "ip_address": "157.211.239.177"
              }
            },
            "previous": "Verify employee paperwork",
            "type": "name_changed"
          },
          {
            "current": "true",
            "key": "required",
            "originated_from": {
              "from_ui": {
                "ip_address": "157.211.239.177"
              }
            },
            "previous": "false",
            "type": "custom_field_changed"
          }
        ]
      },
      "received_at": "2024-03-06T04:55:45.247971922Z",
      "source": "zendesk",
      "type": "record_updated"
    }
  ],
  "links": [
    {
      "next": "/api/v2/task_lists/01KFGZJGMQ3NA9DNX34Y5YGGYM/events?page%5Bafter%5D=abc123&page%5Bsize%5D=10"
    }
  ],
  "meta": {
    "after_cursor": "abc123",
    "has_more": true
  }
}

403 Forbidden

// Status 403 Forbidden

{
  "errors": [
    {
      "code": "StartTimestampNotValid",
      "id": "c21d8981-8940-419b-907b-7f7a2ba22cca",
      "title": "Start Timestamp not valid"
    }
  ]
}

404 Not Found

// Status 404 Not Found

{
  "errors": [
    {
      "code": "StartTimestampNotValid",
      "id": "c21d8981-8940-419b-907b-7f7a2ba22cca",
      "title": "Start Timestamp not valid"
    }
  ]
}