Tasks Service

The Tasks service allows you to use the Google Tasks API in Apps Script. This API gives users the ability to manage their tasks in Gmail.


For detailed information on this service, see the reference documentation for the Tasks API. Like all advanced services in Apps Script, the Tasks service uses the same objects, methods, and parameters as the public API. For more information, see How method signatures are determined.

To report issues and find other support, see the Tasks support guide.

Sample application

The sample web application Simple Tasks demonstrates how to use the Tasks service for both read and write operations. You can view the full source code on our GitHub repository.

Sample code

The sample code below uses version 1 of the API.

List task lists

This sample lists the task lists in your account.

 * Lists tasks titles and IDs.
function listTaskLists() {
  var taskLists = Tasks.Tasklists.list();
  if (taskLists.items) {
    for (var i = 0; i < taskLists.items.length; i++) {
      var taskList = taskLists.items[i];
      Logger.log('Task list with title "%s" and ID "%s" was found.',
          taskList.title, taskList.id);
  } else {
    Logger.log('No task lists found.');

List tasks

This sample lists the tasks within a given task list.

 * Lists task items for a provided tasklist ID.
 * @param  {string} taskListId The tasklist ID.
function listTasks(taskListId) {
  var tasks = Tasks.Tasks.list(taskListId);
  if (tasks.items) {
    for (var i = 0; i < tasks.items.length; i++) {
      var task = tasks.items[i];
      Logger.log('Task with title "%s" and ID "%s" was found.',
          task.title, task.id);
  } else {
    Logger.log('No tasks found.');

Add task

This sample adds a new task to a task list.

 * Adds a task to a tasklist.
 * @param {string} taskListId The tasklist to add to.
function addTask(taskListId) {
  var task = {
    title: 'Pick up dry cleaning',
    notes: 'Remember to get this done!'
  task = Tasks.Tasks.insert(task, taskListId);
  Logger.log('Task with ID "%s" was created.', task.id);