Lists

class clickupython.models.SingleList(*, id: str = None, name: str = None, deleted: bool = None, archived: bool = None, orderindex: int = None, override_statuses: bool = None, priority: Priority = None, assignee: Asssignee = None, due_date: str = None, start_date: str = None, folder: ListFolder = None, space: ListFolder = None, statuses: List[StatusElement] = None, inbound_address: str = None, permission_level: str = None, content: str = None, status: Status = None, task_count: int = None, start_date_time: str = None, due_date_time: bool = None)

Bases: BaseModel

archived: bool

assignee: Asssignee

build_list()

content: Optional[str]

deleted: bool

due_date: str

due_date_time: Optional[bool]

folder: ListFolder

id: str

inbound_address: str

name: str

orderindex: int

override_statuses: bool

permission_level: str

priority: Optional[Priority]

space: ListFolder

start_date: str

start_date_time: Optional[str]

status: Optional[Status]

statuses: Optional[List[StatusElement]]

task_count: Optional[int]

Creating a List

Here’s how to create a new ClickupClient instance and validate a personal API key with the ClickUp API and create a new task with a due date. When creating a new task, the only required arguments are list_id and name. Name will be the title of your list on ClickUp.

Example:

c = client.ClickUpClient("YOUR_API_KEY")
t = c.create_task("LIST_ID", name="Test Task", due_date="march 2 2021")

Fetching a Single Task

Example: Lookup via ClickUpClient:

c = client.ClickUpClient("YOUR_API_KEY")
task = c.get_task(task_id)

print(task.name)

Fetching all Tasks from a List

You can quickly get all tasks for a given list via the list id:

Example:

c = client.ClickUpClient("YOUR_API_KEY")
tasks = c.get_tasks("list_id")

Filtering Tasks

Example:

c = client.ClickUpClient("YOUR_API_KEY")
tasks = c.get_tasks("list_id", date_updated_gt="august 1 2021",
       assignees=["4523","4562","5871"], include_closed=True)

This example will return all tasks that have been updated after August 1st, 2021 and are assigned to users with the ids of 4523, 4562, and 5871. This request will also include tasks that have been marked as “closed.”

Example:

c = client.ClickUpClient("YOUR_API_KEY")
tasks = c.get_tasks("list_id", subtasks=True,
        statuses=["todo", "in progress"])

This example will return all tasks and subtasks that are marked as “Todo” and “In Progress”. These values can be changed depending on the statuses you have available in your list.

You can extend the calls above by passing any of the arguments to the get_tasks method. You can use as many or as few as you would like.

Working With Tasks

Now that you have a list of Task objects you can access the attributes of each task in a number of ways:

Example: Loop:

c = client.ClickUpClient("YOUR_API_KEY")
tasks = c.get_tasks(list_id)

for task in tasks:
   print(task.name)

Example: Direct Access via an Index:

c = client.ClickUpClient("YOUR_API_KEY")
tasks = c.get_tasks(list_id)

print(tasks[0].name])

Getting Tasks Associated with a List Object

Certain calls can be made directly from a parent object. We can access a single Task or all Tasks associated with a List with the following methods.

Note

IMPORTANT - When calling a method from a parent object you must pass in a reference to the ClickUpClient object as the first argument.

Example: Lookup Tasks via a List Object:

c = client.ClickUpClient("YOUR_API_KEY")
list = c.get_list(list_id)
tasks = list.get_tasks(c)
filtered_tasks = list.get_tasks(c, subtasks=True, statuses=["todo", "in progress"])
task = list.get_task(c, task_id)

List Methods

get_list()

ClickUpClient.get_list(list_id: str) → SingleList

Fetches a single list item from a given list id and returns a List object.

Args:

list_id (str):: The id of the ClickUp list.

Returns:

models.SingleList:: Returns an object of type List.

get_lists()

ClickUpClient.get_lists(folder_id: str) → AllLists

Fetches all lists from a given folder id and returns a list of List objects.

Args:

folder_id (str):: The ID of the ClickUp folder to be returned.

Returns:

list.AllLists:: Returns a list of type AllLists.

create_list()

ClickUpClient.create_list(folder_id: str, name: str, content: str, due_date: str, priority: int, status: str) → SingleList

Creates and returns a List object in a folder from a given folder ID.

Args:

folder_id (str):: The ID of the ClickUp folder.
name (str):: The name of the created list.
content (str):: The description content of the created list.
due_date (str):: The due date of the created list.
priority (int):: An integer 1 : Urgent, 2 : High, 3 : Normal, 4 : Low.
status (str):: Refers to the List color rather than the task Statuses available in the List.

Returns:

list.SingleList:: Returns an object of type SingleList.