Skip to main content

​
Overview

The Google Tasks API allows you to manage task lists and individual tasks programmatically. API Name: tasks
Version: v1
Official Documentation: Tasks API Reference

​
Common Resources

​
Task Lists

Manage task lists (containers for tasks).
​
tasklist
string
required
The task list ID or @default for the default list
​
title
string
The task list title

​
Tasks

Manage individual tasks.
​
tasklist
string
required
The task list ID
​
task
string
The task ID
​
title
string
The task title
​
due
string
Due date (RFC 3339 timestamp)

​
Common Methods

​
List Task Lists

gws tasks tasklists list
​
items
array
Array of task list objects
​
id
string
The task list ID
​
title
string
The task list title
​
updated
string
Last modification time

​
Get Task List

gws tasks tasklists get --params '{
  "tasklist": "@default"
}'

​
Create Task List

gws tasks tasklists insert --json '{
  "title": "Work Tasks"
}'

​
List Tasks

gws tasks tasks list --params '{
  "tasklist": "@default",
  "showCompleted": false
}'
​
items
array
Array of task objects
​
id
string
The task ID
​
title
string
The task title
​
status
string
Task status: needsAction or completed
​
due
string
Due date (RFC 3339 timestamp)

​
Create Task

gws tasks tasks insert \
  --params '{"tasklist": "@default"}' \
  --json '{
    "title": "Review pull request",
    "notes": "Check PR #123 for the API changes",
    "due": "2026-03-10T00:00:00.000Z"
  }'

​
Get Task

gws tasks tasks get --params '{
  "tasklist": "@default",
  "task": "task123"
}'

​
Update Task

gws tasks tasks update \
  --params '{"tasklist": "@default", "task": "task123"}' \
  --json '{
    "title": "Updated task title",
    "status": "completed"
  }'

​
Delete Task

gws tasks tasks delete --params '{
  "tasklist": "@default",
  "task": "task123"
}'

​
Task Operations

gws tasks tasks update \
  --params '{"tasklist": "@default", "task": "task123"}' \
  --json '{"status": "completed"}'

​
Response Format

Task list response: 
{
  "items": [
    {
      "id": "MDAxNjM4NTQ2NzY4NTQ2NzY4NTQ",
      "title": "My Tasks",
      "updated": "2026-03-05T10:30:00.000Z",
      "selfLink": "https://www.googleapis.com/tasks/v1/users/@me/lists/MDAxNjM4NTQ2NzY4NTQ2NzY4NTQ"
    }
  ]
}
Task response: 
{
  "id": "task123",
  "title": "Review pull request",
  "notes": "Check PR #123 for the API changes",
  "status": "needsAction",
  "due": "2026-03-10T00:00:00.000Z",
  "updated": "2026-03-05T14:20:00.000Z",
  "selfLink": "https://www.googleapis.com/tasks/v1/lists/@default/tasks/task123"
}

​
Key Resources

  • tasklists - Manage task lists
  • tasks - Manage tasks within lists

​
Task Hierarchy

Tasks can be organized hierarchically with parent-child relationships: 
# Create parent task
gws tasks tasks insert \
  --params '{"tasklist": "@default"}' \
  --json '{"title": "Project Launch"}'

# Create subtask
gws tasks tasks insert \
  --params '{"tasklist": "@default", "parent": "parentTaskId"}' \
  --json '{"title": "Write documentation"}'

​
Filtering Tasks

# Show only incomplete tasks
gws tasks tasks list --params '{
  "tasklist": "@default",
  "showCompleted": false
}'

# Show tasks updated after a date
gws tasks tasks list --params '{
  "tasklist": "@default",
  "updatedMin": "2026-03-01T00:00:00.000Z"
}'

# Show tasks due before a date
gws tasks tasks list --params '{
  "tasklist": "@default",
  "dueMax": "2026-03-31T23:59:59.000Z"
}'

​
Learn More

​
Schema Inspection

Before calling any method, inspect its schema: 
gws schema tasks.tasklists.list
gws schema tasks.tasks.insert