> For the complete documentation index, see [llms.txt](https://docs.kognitos.com/llms.txt). Markdown versions of documentation pages are available by appending `.md` to page URLs; this page is available as [Markdown](https://docs.kognitos.com/legacy/legacy-experience/books/reference/googletasks.md).

# Google Tasks

Procedures and concepts for the Google Tasks integration.

{% hint style="info" %}
The following documentation is for **Google Tasks v2.11.0** *(BDK)*.
{% endhint %}

## Overview

Google Tasks provides lightweight task and task-list management integrated with Google Workspace. This integration enables automated task creation, completion, retrieval, and list management workflows. Coordinate to-dos and personal task lists alongside your other automated processes.

## Prerequisites

### 1. Required Books

The following Book(s) need to be added to your agent so it can learn and understand the automation procedures defined within them:

* **Google Tasks**

#### How to Add the Book(s)

1. Go to **Books** → **All Books**.
2. Search for the name of the book and click on it.
3. Click on <kbd>**Install**</kbd> or <kbd>**Add Connection**</kbd> to add the book to your agent.
4. If adding a connection, you'll be prompted for [**connectivity**](#connectivity) details.

## Connectivity

This section outlines the available methods for connecting to the Book, along with the required configuration details for each.

## Procedures

### to clear completed tasks from *google tasks*

Clear all completed tasks from a Google Tasks task list.

**Input Concepts**

| Concept        | Description                                                   | Type   | Required | Default Value |
| -------------- | ------------------------------------------------------------- | ------ | -------- | ------------- |
| `task list id` | The task list identifier (default: user's default task list). | `text` | No       | @default      |

**Output Concepts**

| Concept  | Description             | Type   |
| -------- | ----------------------- | ------ |
| `answer` | A confirmation message. | `text` |

**Examples**

Clear completed tasks from the default list

```generic
clear completed tasks from google tasks
```

### to complete a (task) in *google tasks*

Mark a task as completed in Google Tasks.

**Input Concepts**

| Concept        | Description                                                   | Type   | Required | Default Value |
| -------------- | ------------------------------------------------------------- | ------ | -------- | ------------- |
| `task id`      | The task identifier to complete.                              | `text` | Yes      | (no default)  |
| `task list id` | The task list identifier (default: user's default task list). | `text` | No       | @default      |

**Output Concepts**

| Concept                | Description         | Type          |
| ---------------------- | ------------------- | ------------- |
| [`task`](#google-task) | The completed task. | `google task` |

**Examples**

Complete a task

```generic
complete a task in google tasks where the task id is "dGFzazEyMzQ"
```

### to create a (task list) in *google tasks*

Create a new task list in Google Tasks.

**Input Concepts**

| Concept | Description                     | Type   | Required | Default Value |
| ------- | ------------------------------- | ------ | -------- | ------------- |
| `title` | The title of the new task list. | `text` | Yes      | (no default)  |

**Output Concepts**

| Concept                          | Description            | Type               |
| -------------------------------- | ---------------------- | ------------------ |
| [`task list`](#google-task-list) | The created task list. | `google task list` |

**Examples**

Create a task list

```generic
create a task list in google tasks where the title is "Work Projects"
```

### to create a (task) in *google tasks*

Create a new task in a Google Tasks task list.

**Input Concepts**

| Concept        | Description                                                          | Type   | Required | Default Value |
| -------------- | -------------------------------------------------------------------- | ------ | -------- | ------------- |
| `title`        | The title of the new task.                                           | `text` | Yes      | (no default)  |
| `task list id` | The task list identifier (default: user's default task list).        | `text` | No       | @default      |
| `notes`        | Optional notes or description for the task.                          | `text` | No       | (no default)  |
| `due`          | Optional due date (RFC 3339 timestamp, e.g. "2026-06-15T00:00:00Z"). | `text` | No       | (no default)  |

**Output Concepts**

| Concept                | Description       | Type          |
| ---------------------- | ----------------- | ------------- |
| [`task`](#google-task) | The created task. | `google task` |

**Examples**

Create a simple task

```generic
create a task in google tasks where the title is "Review quarterly report"
```

Create a task with notes and a due date

```generic
create a task in google tasks where
  the title is "Prepare presentation"
  the notes is "Include Q2 metrics and projections"
  the due is "2026-06-15T00:00:00Z"
```

### to delete a task from *google tasks*

Delete a task from a Google Tasks task list.

**Input Concepts**

| Concept        | Description                                                   | Type   | Required | Default Value |
| -------------- | ------------------------------------------------------------- | ------ | -------- | ------------- |
| `task id`      | The task identifier to delete.                                | `text` | Yes      | (no default)  |
| `task list id` | The task list identifier (default: user's default task list). | `text` | No       | @default      |

**Output Concepts**

| Concept  | Description             | Type   |
| -------- | ----------------------- | ------ |
| `answer` | A confirmation message. | `text` |

**Examples**

Delete a task

```generic
delete a task from google tasks where the task id is "dGFzazEyMzQ"
```

### to delete a task list from *google tasks*

Delete a task list from Google Tasks.

**Input Concepts**

| Concept        | Description                                | Type   | Required | Default Value |
| -------------- | ------------------------------------------ | ------ | -------- | ------------- |
| `task list id` | The identifier of the task list to delete. | `text` | Yes      | (no default)  |

**Output Concepts**

| Concept  | Description             | Type   |
| -------- | ----------------------- | ------ |
| `answer` | A confirmation message. | `text` |

**Examples**

Delete a task list

```generic
delete a task list from google tasks where the task list id is "MDIxMjE2NTc"
```

### to get a (task) from *google tasks*

Get a specific task from Google Tasks by its identifier.

**Input Concepts**

| Concept        | Description                                                   | Type   | Required | Default Value |
| -------------- | ------------------------------------------------------------- | ------ | -------- | ------------- |
| `task id`      | The task identifier.                                          | `text` | Yes      | (no default)  |
| `task list id` | The task list identifier (default: user's default task list). | `text` | No       | @default      |

**Output Concepts**

| Concept                | Description         | Type          |
| ---------------------- | ------------------- | ------------- |
| [`task`](#google-task) | The requested task. | `google task` |

**Examples**

Retrieve a task by ID

```generic
get a task from google tasks where the task id is "dGFzazEyMzQ"
```

### to get some (task lists) from *google tasks*

Get all task lists from Google Tasks.

**Input Concepts**

| Concept       | Description                                            | Type     | Required | Default Value |
| ------------- | ------------------------------------------------------ | -------- | -------- | ------------- |
| `max results` | Maximum number of task lists to return (default: 100). | `number` | No       | 100           |

**Output Concepts**

| Concept                           | Description             | Type               |
| --------------------------------- | ----------------------- | ------------------ |
| [`task lists`](#google-task-list) | The list of task lists. | `google task list` |

**Examples**

Retrieve all task lists

```generic
get task lists from google tasks
```

Retrieve task lists with a limit

```generic
get task lists from google tasks where the max results is 10
```

### to get some (tasks) from *google tasks*

Get tasks from a Google Tasks task list.

**Input Concepts**

| Concept          | Description                                                                      | Type      | Required | Default Value |
| ---------------- | -------------------------------------------------------------------------------- | --------- | -------- | ------------- |
| `task list id`   | The task list identifier (default: user's default task list).                    | `text`    | No       | @default      |
| `show completed` | Whether to include completed tasks (default: true).                              | `boolean` | No       | True          |
| `show hidden`    | Whether to include hidden tasks (default: false).                                | `boolean` | No       | False         |
| `max results`    | Maximum number of tasks to return (default: 100).                                | `number`  | No       | 100           |
| `due min`        | Lower bound for task due date (RFC 3339 timestamp, e.g. "2026-01-01T00:00:00Z"). | `text`    | No       | (no default)  |
| `due max`        | Upper bound for task due date (RFC 3339 timestamp, e.g. "2026-12-31T23:59:59Z"). | `text`    | No       | (no default)  |

**Output Concepts**

| Concept                 | Description        | Type          |
| ----------------------- | ------------------ | ------------- |
| [`tasks`](#google-task) | The list of tasks. | `google task` |

**Examples**

Retrieve all tasks from the default list

```generic
get tasks from google tasks
```

Retrieve tasks from a specific list

```generic
get tasks from google tasks where the task list id is "MDIxMjE2NTc"
```

Retrieve only incomplete tasks

```generic
get tasks from google tasks where the show completed is false
```

### to move a (task) in *google tasks*

Move a task to a different position in its task list.

Use parent\_task\_id to make it a subtask. Use previous\_task\_id to place it after a specific sibling task.

**Input Concepts**

| Concept            | Description                                                   | Type   | Required | Default Value |
| ------------------ | ------------------------------------------------------------- | ------ | -------- | ------------- |
| `task id`          | The task identifier to move.                                  | `text` | Yes      | (no default)  |
| `task list id`     | The task list identifier (default: user's default task list). | `text` | No       | @default      |
| `parent task id`   | Optional parent task identifier to make this a subtask.       | `text` | No       | (no default)  |
| `previous task id` | Optional identifier of the task to place this after.          | `text` | No       | (no default)  |

**Output Concepts**

| Concept                | Description                               | Type          |
| ---------------------- | ----------------------------------------- | ------------- |
| [`task`](#google-task) | The moved task with its updated position. | `google task` |

**Examples**

Make a task a subtask of another task

```generic
move a task in google tasks where
  the task id is "dGFzazEyMzQ"
  the parent task id is "cGFyZW50MTIz"
```

Move a task after a sibling

```generic
move a task in google tasks where
  the task id is "dGFzazEyMzQ"
  the previous task id is "c2libGluZzEy"
```

### to update a (task) in *google tasks*

Update an existing task in Google Tasks.

**Input Concepts**

| Concept        | Description                                                     | Type   | Required | Default Value |
| -------------- | --------------------------------------------------------------- | ------ | -------- | ------------- |
| `task id`      | The task identifier to update.                                  | `text` | Yes      | (no default)  |
| `task list id` | The task list identifier (default: user's default task list).   | `text` | No       | @default      |
| `title`        | New title for the task.                                         | `text` | No       | (no default)  |
| `notes`        | New notes for the task.                                         | `text` | No       | (no default)  |
| `status`       | New status ("needsAction" or "completed").                      | `text` | No       | (no default)  |
| `due`          | New due date (RFC 3339 timestamp, e.g. "2026-06-15T00:00:00Z"). | `text` | No       | (no default)  |

**Output Concepts**

| Concept                | Description       | Type          |
| ---------------------- | ----------------- | ------------- |
| [`task`](#google-task) | The updated task. | `google task` |

**Examples**

Mark a task as completed

```generic
update a task in google tasks where
  the task id is "dGFzazEyMzQ"
  the status is "completed"
```

Update a task title and due date

```generic
update a task in google tasks where
  the task id is "dGFzazEyMzQ"
  the title is "Updated title"
  the due is "2026-07-01T00:00:00Z"
```

## Concepts

### Google task

A Google Tasks task.

| Field Name      | Description                                            | Type                |
| --------------- | ------------------------------------------------------ | ------------------- |
| `title`         | The title of the task.                                 | `text`              |
| `id`            | The task identifier.                                   | `optional[text]`    |
| `notes`         | Notes describing the task.                             | `optional[text]`    |
| `status`        | The status of the task ("needsAction" or "completed"). | `optional[text]`    |
| `due`           | The due date of the task (RFC 3339 timestamp).         | `optional[text]`    |
| `completed`     | The completion date of the task (RFC 3339 timestamp).  | `optional[text]`    |
| `parent`        | The parent task identifier (for subtasks).             | `optional[text]`    |
| `position`      | The position among sibling tasks.                      | `optional[text]`    |
| `updated`       | The last modification time.                            | `optional[text]`    |
| `web_view_link` | An absolute link to the task in Google Tasks Web UI.   | `optional[text]`    |
| `deleted`       | Whether the task has been deleted.                     | `optional[boolean]` |
| `hidden`        | Whether the task is hidden.                            | `optional[boolean]` |

### Google task list

A Google Tasks task list.

| Field Name | Description                                  | Type             |
| ---------- | -------------------------------------------- | ---------------- |
| `id`       | The task list identifier.                    | `text`           |
| `title`    | The title of the task list.                  | `text`           |
| `updated`  | The last modification time of the task list. | `optional[text]` |