User Task Lists

A user task list represents the tasks assigned to a particular user. It provides API access to a user’s “My Tasks” view in Asana.

A user’s “My Tasks” represent all of the tasks assigned to that user. It is visually divided into regions based on the task’s assignee_status for Asana users to triage their tasks based on when they can address them. When building an integration it’s worth noting that tasks with due dates will automatically move through assignee_status states as their due dates approach; read up on task auto-promotion for more infomation.

User Task Lists have the following fields:
Field Description
id 1234 Read-only. Globally unique ID of the user task list. Note: This field is under active migration to the gid field—please see our blog post for more information.
gid "1234" Read-only. Globally unique ID of the user task list.
resource_type "user_task_list" Read-only. The resource type of this resource. The value for this resource is always user_task_list.
name "My Tasks" Read-only. The name of the user task list.
owner { id: 12345, gid: "12345", resource_type: "user", name: 'Tim Bizarro' } null Read-only. The owner of the user task list, i.e. the person whose My Tasks is represented by this resource.
workspace { id: 14916, gid: "14916", name: 'My Workspace' } Read-only. The workspace in which the user task list is located.

GET A USER’S USER TASK LIST

GET    /users/{user_gid}/user_task_list

Returns the full record for the user task list for the given user

Parameter Description
user_gid "14641" "me" "sashimi@asana.com" Required: An identifier for the user. Can be one of an email address, the globally unique identifier for the user, or the keyword me to indicate the current user making the request.
workspace "1331" Required: Globally unique identifier for the workspace or organization.
# Request
curl -H "Authorization: Bearer <personal_access_token>" \
https://app.asana.com/api/1.0/users/12345/user_task_list?workspace=1337

# Response
HTTP/1.1 200
{
  "data": [
    {
      "id": 16284,
      "gid": "16284",
      "resource_type": "user_task_list",
      "name": "My Tasks",
      "owner": {
        "id": 12345,
        "gid": "12345",
        "name": "Tim Bizzaro",
        "resource_type": "user"
      },
      "workspace": {
        "id": 1337,
        "gid": "1337",
        "resource_type": "workspace",
        "name": "My Favorite Workspace"
      }
    }
  ]
}

GET A USER TASK LIST

GET    /user_task_lists/{user_task_list_gid}

Returns the full record for a user task list.

Parameter Description
user_task_list_gid "16284" Required: Globally unique identifier for the user task list.
# Request
curl -H "Authorization: Bearer <personal_access_token>" \
https://app.asana.com/api/1.0/user_task_lists/16284

# Response
HTTP/1.1 200
{
  "data": [
    {
      "id": 16284,
      "gid": "16284",
      "resource_type": "user_task_list",
      "name": "My Tasks",
      "owner": {
        "id": 12345,
        "gid": "12345",
        "name": "Tim Bizzaro",
        "resource_type": "user"
      },
      "workspace": {
        "id": 1337,
        "gid": "1337",
        "resource_type": "workspace",
        "name": "My Favorite Workspace"
      }
    }
  ]
}

GET TASKS IN A USER TASK LIST

GET    /user_task_lists/{user_task_list_gid}/tasks

Returns the compact list of tasks in a user’s My Tasks list. The returned tasks will be in order within each assignee status group of Inbox, Today, and Upcoming.

Note: tasks in Later have a different ordering in the Asana web app than the other assignee status groups; this endpoint will still return them in list order in Later (differently than they show up in Asana, but the same order as in Asana’s mobile apps).

Note: Access control is enforced for this endpoint as with all Asana API endpoints, meaning a user’s private tasks will be filtered out if the API-authenticated user does not have access to them.

Note: Both complete and incomplete tasks are returned by default unless they are filtered out (for example, setting completed_since=now will return only incomplete tasks, which is the default view for “My Tasks” in Asana.)

Parameter Description
user_task_list_gid "16284" Required: The user task list in which to search for tasks.
completed_since '2012-02-22T02:06:58.158Z' now Only return tasks that are either incomplete or that have been completed since this time.