get_tasks
Retrieve tasks from a ClickUp list using list ID or name, with options to filter by status, dates, or sort order for focused task management.
Instructions
Retrieve tasks from a list with optional filtering. You MUST provide either:
listId (preferred)
listName
Use filters to narrow down results by status, dates, etc.
Input Schema
TableJSON Schema
| Name | Required | Description | Default |
|---|---|---|---|
| listId | No | ID of list to get tasks from (preferred). Use this instead of listName if you have it. | |
| listName | No | Name of list to get tasks from. Only use if you don't have listId. | |
| archived | No | Include archived tasks | |
| page | No | Page number for pagination (starts at 0) | |
| order_by | No | Sort field: due_date, created, updated | |
| reverse | No | Reverse sort order (descending) | |
| subtasks | No | Include subtasks | |
| statuses | No | Filter by status names (e.g. ['To Do', 'In Progress']) |
Implementation Reference
- src/tools/task.ts:1372-1431 (handler)Main execution handler for get_tasks tool: resolves list by ID or name using workspace hierarchy, prepares TaskFilters, calls taskService.getTasks, formats tasks with readable dates and assignees, returns JSON response.
export async function handleGetTasks(parameters: any) { const { listId, listName, archived, page, order_by, reverse, subtasks, statuses, include_closed, assignees, due_date_gt, due_date_lt, date_created_gt, date_created_lt, date_updated_gt, date_updated_lt, custom_fields } = parameters; let targetListId = listId; // If no listId but listName is provided, look up the list ID if (!targetListId && listName) { const hierarchy = await workspaceService.getWorkspaceHierarchy(); const listInfo = workspaceService.findIDByNameInHierarchy(hierarchy, listName, 'list'); if (!listInfo) { throw new Error(`List "${listName}" not found`); } targetListId = listInfo.id; } if (!targetListId) { throw new Error("Either listId or listName must be provided"); } // Prepare filter options - remove archived as it's not in TaskFilters const filters: TaskFilters = { page, order_by, reverse, subtasks, statuses }; // Get tasks with filters const tasks = await taskService.getTasks(targetListId, filters); // Format the tasks data to be more API friendly const formattedTasks = tasks.map(task => ({ id: task.id, name: task.name, status: task.status?.status || 'Unknown', url: task.url, due_date: task.due_date ? formatDueDate(Number(task.due_date)) : undefined, due_date_raw: task.due_date, priority: task.priority?.priority, assignees: task.assignees?.map(a => a.username) || [] })); // Format response return { content: [{ type: "text", text: JSON.stringify({ total: tasks.length, tasks: formattedTasks }, null, 2) }] }; } - src/tools/task.ts:578-684 (schema)Tool schema definition for 'get_tasks' including name, description, and detailed inputSchema for parameters like listId/listName, pagination, sorting, subtasks, and status filters.
export const getTasksTool = { name: "get_tasks", description: "Retrieve tasks from a list with optional filtering. You MUST provide either:\n1. listId (preferred)\n2. listName\n\nUse filters to narrow down results by status, dates, etc.", inputSchema: { type: "object", properties: { listId: { type: "string", description: "ID of list to get tasks from (preferred). Use this instead of listName if you have it." }, listName: { type: "string", description: "Name of list to get tasks from. Only use if you don't have listId." }, archived: { type: "boolean", description: "Include archived tasks" }, page: { type: "number", description: "Page number for pagination (starts at 0)" }, order_by: { type: "string", description: "Sort field: due_date, created, updated" }, reverse: { type: "boolean", description: "Reverse sort order (descending)" }, subtasks: { type: "boolean", description: "Include subtasks" }, statuses: { type: "array", items: { type: "string" }, description: "Filter by status names (e.g. ['To Do', 'In Progress'])" } }, required: [] }, async handler({ listId, listName, archived, page, order_by, reverse, subtasks, statuses }: { listId?: string; listName?: string; archived?: boolean; page?: number; order_by?: 'id' | 'created' | 'updated' | 'due_date'; reverse?: boolean; subtasks?: boolean; statuses?: string[]; }) { let targetListId = listId; // If no listId but listName is provided, look up the list ID if (!targetListId && listName) { const hierarchy = await workspaceService.getWorkspaceHierarchy(); const listInfo = workspaceService.findIDByNameInHierarchy(hierarchy, listName, 'list'); if (!listInfo) { throw new Error(`List "${listName}" not found`); } targetListId = listInfo.id; } if (!targetListId) { throw new Error("Either listId or listName must be provided"); } // Prepare filter options - remove archived as it's not in TaskFilters const filters: TaskFilters = { page, order_by, reverse, subtasks, statuses }; // Get tasks with filters const tasks = await taskService.getTasks(targetListId, filters); // Format the tasks data to be more API friendly const formattedTasks = tasks.map(task => ({ id: task.id, name: task.name, status: task.status?.status || 'Unknown', url: task.url, due_date: task.due_date ? formatDueDate(Number(task.due_date)) : undefined, due_date_raw: task.due_date, priority: task.priority?.priority, assignees: task.assignees?.map(a => a.username) || [] })); // Format response return { content: [{ type: "text", text: JSON.stringify({ total: tasks.length, tasks: formattedTasks }, null, 2) }] }; } }; - src/server.ts:95-156 (registration)Server registration: dispatches 'get_tasks' tool calls to handleGetTasks in the CallToolRequestSchema handler switch statement.
server.setRequestHandler(CallToolRequestSchema, async (req) => { const { name, arguments: params } = req.params; // Handle tool calls by routing to the appropriate handler switch (name) { case "get_workspace_hierarchy": return handleGetWorkspaceHierarchy(); case "create_task": return handleCreateTask(params); case "update_task": return handleUpdateTask(params); case "move_task": return handleMoveTask(params); case "duplicate_task": return handleDuplicateTask(params); case "get_task": return handleGetTask(params); case "get_tasks": return handleGetTasks(params); case "delete_task": return handleDeleteTask(params); case "create_bulk_tasks": return handleCreateBulkTasks(params); case "update_bulk_tasks": return handleUpdateBulkTasks(params as { tasks: any[] }); case "move_bulk_tasks": return handleMoveBulkTasks(params as { tasks: any[], targetListId?: string, targetListName?: string }); case "delete_bulk_tasks": return handleDeleteBulkTasks(params as { tasks: any[] }); case "create_list": return handleCreateList(params); case "create_list_in_folder": return handleCreateListInFolder(params); case "get_list": return handleGetList(params); case "update_list": return handleUpdateList(params); case "delete_list": return handleDeleteList(params); case "create_folder": return handleCreateFolder(params); case "get_folder": return handleGetFolder(params); case "update_folder": return handleUpdateFolder(params); case "delete_folder": return handleDeleteFolder(params); default: throw new Error(`Unknown tool: ${name}`); } }); server.setRequestHandler(ListPromptsRequestSchema, async () => { return { prompts: [] }; }); server.setRequestHandler(GetPromptRequestSchema, async () => { throw new Error("Prompt not found"); }); return server; } - src/server.ts:67-91 (registration)Server registration: includes getTasksTool in the list returned by ListToolsRequestSchema for tool discovery.
server.setRequestHandler(ListToolsRequestSchema, async () => { return { tools: [ workspaceHierarchyTool, createTaskTool, getTaskTool, getTasksTool, updateTaskTool, moveTaskTool, duplicateTaskTool, deleteTaskTool, createBulkTasksTool, updateBulkTasksTool, moveBulkTasksTool, deleteBulkTasksTool, createListTool, createListInFolderTool, getListTool, updateListTool, deleteListTool, createFolderTool, getFolderTool, updateFolderTool, deleteFolderTool ] - src/services/clickup/task.ts:90-132 (helper)Underlying service method implementing ClickUp API call to fetch tasks from a list with query parameters for all supported filters, returns raw ClickUpTask[]
async getTasks(listId: string, filters: TaskFilters = {}): Promise<ClickUpTask[]> { this.logOperation('getTasks', { listId, filters }); try { return await this.makeRequest(async () => { const params = new URLSearchParams(); // Add all filters to the query parameters if (filters.include_closed) params.append('include_closed', String(filters.include_closed)); if (filters.subtasks) params.append('subtasks', String(filters.subtasks)); if (filters.page) params.append('page', String(filters.page)); if (filters.order_by) params.append('order_by', filters.order_by); if (filters.reverse) params.append('reverse', String(filters.reverse)); if (filters.statuses && filters.statuses.length > 0) { filters.statuses.forEach(status => params.append('statuses[]', status)); } if (filters.assignees && filters.assignees.length > 0) { filters.assignees.forEach(assignee => params.append('assignees[]', assignee)); } if (filters.due_date_gt) params.append('due_date_gt', String(filters.due_date_gt)); if (filters.due_date_lt) params.append('due_date_lt', String(filters.due_date_lt)); if (filters.date_created_gt) params.append('date_created_gt', String(filters.date_created_gt)); if (filters.date_created_lt) params.append('date_created_lt', String(filters.date_created_lt)); if (filters.date_updated_gt) params.append('date_updated_gt', String(filters.date_updated_gt)); if (filters.date_updated_lt) params.append('date_updated_lt', String(filters.date_updated_lt)); // Handle custom fields if present if (filters.custom_fields) { Object.entries(filters.custom_fields).forEach(([key, value]) => { params.append(`custom_fields[${key}]`, String(value)); }); } const response = await this.client.get<TasksResponse>( `/list/${listId}/task?${params.toString()}` ); return response.data.tasks; }); } catch (error) { throw this.handleError(error, `Failed to get tasks from list ${listId}`); } }