ClickUp API筛选NIRV复选框勾选任务无结果问题排查

我使用Python调用ClickUp API，想要列出指定文件夹下所有自定义复选框字段“NIRV”已勾选的任务。但明明确认列表900201998483中存在符合条件的任务，代码运行后却全部返回“无符合条件任务”。

原代码如下：

import requests

# Constants
API_KEY = 'XXXXXXXXXXXXXXXXXXXXXXXXXXXXXXXXXXXXXXXX'
FOLDER_ID = '544444444444444444444'

# Function to get lists inside a folder
def get_lists_in_folder(folder_id):
    url = f"https://api.clickup.com/api/v2/folder/{folder_id}/list"
    headers = {
        "Authorization": API_KEY
    }
    response = requests.get(url, headers=headers)
    response.raise_for_status()
    return response.json()["lists"]

# Function to get tasks from a list
def get_clickup_tasks(list_id):
    url = f"https://api.clickup.com/api/v2/list/{list_id}/task"
    headers = {
        "Authorization": API_KEY
    }
    params = {
        "subtasks": "true",
        "include_closed": "false"  # Exclude closed tasks
    }
    response = requests.get(url, headers=headers, params=params)
    response.raise_for_status()
    return response.json()["tasks"]

# Function to filter tasks with 'NIRV' checkbox checked
def filter_nirvana_tasks(tasks):
    nirvana_tasks = []
    for task in tasks:
        custom_fields = task.get("custom_fields", [])
        for custom_field in custom_fields:
            if custom_field["name"] == "Nirv" and custom_field.get("value") == True:
                nirvana_tasks.append(task)
                break  # Move to the next task once we find the Nirv field checked
    return nirvana_tasks

# Main script
lists = get_lists_in_folder(FOLDER_ID)

for lst in lists:
    list_id = lst['id']
    tasks = get_clickup_tasks(list_id)
    nirvana_tasks = filter_nirvana_tasks(tasks)

    if nirvana_tasks:
        print(f"Tasks in List ID {list_id} with 'NIRV' checked:")
        for task in nirvana_tasks:
            print(f"Task ID: {task['id']}")
    else:
        print(f"No tasks in List ID {list_id} with 'NIRV' checked.")

运行输出：

No tasks in List ID 900201998483 with 'NIRV' checked.
No tasks in List ID 900201249353 with 'NIRV' checked.
No tasks in List ID 900201249363 with 'NIRV' checked.
No tasks in List ID 900201249293 with 'NIRV' checked.
No tasks in List ID 900700176764 with 'NIRV' checked.
...

排查与修正方案 #

1. 字段名称大小写不匹配 #

原代码中判断字段名为"Nirv"，但实际目标字段是"NIRV"，大小写不一致导致无法匹配，需要修正为完全一致的名称。

2. 复选框字段的value值类型问题 #

ClickUp API中，勾选状态的复选框字段返回的value是字符串"true"，而非Python的布尔值True。直接用== True会导致匹配失败，需改为判断字符串值。

3. 任务分页处理 #

ClickUp API的任务列表接口默认每页返回100条任务，如果列表中任务数量超过100条，未处理分页会导致后续任务被遗漏，需要添加分页逻辑获取所有任务。

修正后的完整代码 #

import requests

# Constants
API_KEY = 'XXXXXXXXXXXXXXXXXXXXXXXXXXXXXXXXXXXXXXXX'
FOLDER_ID = '544444444444444444444'

# Function to get lists inside a folder
def get_lists_in_folder(folder_id):
    url = f"https://api.clickup.com/api/v2/folder/{folder_id}/list"
    headers = {
        "Authorization": API_KEY
    }
    response = requests.get(url, headers=headers)
    response.raise_for_status()
    return response.json()["lists"]

# Function to get ALL tasks from a list (handle pagination)
def get_clickup_tasks(list_id):
    url = f"https://api.clickup.com/api/v2/list/{list_id}/task"
    headers = {
        "Authorization": API_KEY
    }
    all_tasks = []
    page = 0
    while True:
        params = {
            "subtasks": "true",
            "include_closed": "false",
            "page": page
        }
        response = requests.get(url, headers=headers, params=params)
        response.raise_for_status()
        data = response.json()
        tasks = data.get("tasks", [])
        if not tasks:
            break
        all_tasks.extend(tasks)
        page += 1
    return all_tasks

# Function to filter tasks with 'NIRV' checkbox checked
def filter_nirvana_tasks(tasks):
    nirvana_tasks = []
    for task in tasks:
        custom_fields = task.get("custom_fields", [])
        for custom_field in custom_fields:
            # 修正字段名称大小写，匹配字符串"true"
            if custom_field["name"] == "NIRV" and custom_field.get("value") == "true":
                nirvana_tasks.append(task)
                break  # 找到匹配字段后直接跳过当前任务的其他字段
    return nirvana_tasks

# Main script
lists = get_lists_in_folder(FOLDER_ID)

for lst in lists:
    list_id = lst['id']
    tasks = get_clickup_tasks(list_id)
    nirvana_tasks = filter_nirvana_tasks(tasks)

    if nirvana_tasks:
        print(f"List ID {list_id} 中已勾选NIRV的任务:")
        for task in nirvana_tasks:
            print(f"任务ID: {task['id']}")
    else:
        print(f"List ID {list_id} 中无已勾选NIRV的任务。")

内容的提问来源于stack exchange，提问作者OOzy Pal