--- updatedAt: 2026-07-01T21:22:52.000Z agentTools: projectIndex: https://developer.clickup.com/llms.txt --- # Get Tasks View the tasks in a List. Responses are limited to 100 tasks per page. You can only view task information of tasks you can access. \ \ This endpoint only includes tasks where the specified `list_id` is their home List. Tasks added to the `list_id` with a different home List are not included in the response by default. To include tasks that exist in multiple lists, use the `include_timl` parameter. \ \ The `time_spent` field displays time tracked in milliseconds, and is only included in the response for tasks with time entries.\ \ Each task's `custom_fields` array only includes Custom Fields applicable to that task's `custom_item_id`. # OpenAPI definition ```json { "openapi": "3.1.0", "info": { "title": "ClickUp API v2 Reference", "description": "The ClickUp API enables you to programmatically access and manage your ClickUp resources.\n\n## Authentication\nThe API supports two authentication methods:\n- **Personal API Token**: Use for testing and personal integrations. Add token to requests with header: `Authorization: pk_...`\n- **OAuth 2.0**: Required for building apps for other users. Uses authorization code flow.\n\n## Getting Started\nOur [Getting Started Guide](https://developer.clickup.com/docs/index) provides a comprehensive overview of how to use the ClickUp API.\n\n## Custom Fields by Task Type\nCustom Fields can be scoped to specific custom task types. Use the Custom Fields endpoints to read each field's `applied_objects` array (`object_type` `19` = custom task type). Task responses only include applicable Custom Fields, and write operations reject or ignore values for non-applicable fields.\n", "contact": {}, "version": "2.0" }, "jsonSchemaDialect": "https://json-schema.org/draft/2020-12/schema", "servers": [ { "url": "https://api.clickup.com/api", "description": "ClickUp", "variables": {} } ], "paths": { "/v2/list/{list_id}/task": { "get": { "summary": "Get Tasks", "tags": [ "Tasks" ], "description": "View the tasks in a List. Responses are limited to 100 tasks per page. You can only view task information of tasks you can access. \\\n \\\nThis endpoint only includes tasks where the specified `list_id` is their home List. Tasks added to the `list_id` with a different home List are not included in the response by default. To include tasks that exist in multiple lists, use the `include_timl` parameter. \\\n \\\nThe `time_spent` field displays time tracked in milliseconds, and is only included in the response for tasks with time entries.\\\n \\\nEach task's `custom_fields` array only includes Custom Fields applicable to that task's `custom_item_id`.", "operationId": "GetTasks", "parameters": [ { "name": "list_id", "in": "path", "description": "To find the list_id: \\ 1. In the Sidebar, hover over the List and click the **ellipsis ...** menu. \\ 2. Select **Copy link.** \\ 3. Use the copied URL to find the list_id. The list_id is the number that follows /li in the URL.", "required": true, "style": "simple", "schema": { "type": "number", "contentEncoding": "double", "examples": [ 123 ] } }, { "name": "archived", "in": "query", "description": "", "style": "form", "explode": true, "schema": { "type": "boolean", "examples": [ false ] } }, { "name": "include_markdown_description", "in": "query", "description": "To return task descriptions in Markdown format, use `?include_markdown_description=true`.", "style": "form", "explode": true, "schema": { "type": "boolean", "examples": [ true ] } }, { "name": "page", "in": "query", "description": "Page to fetch (starts at 0).", "style": "form", "explode": true, "schema": { "type": "integer", "contentEncoding": "int32" } }, { "name": "order_by", "in": "query", "description": "Order by a particular field. By default, tasks are ordered by `created`.\\\n \\\nOptions include: `id`, `created`, `updated`, and `due_date`.", "style": "form", "explode": true, "schema": { "type": "string" } }, { "name": "reverse", "in": "query", "description": "Tasks are displayed in reverse order.", "style": "form", "explode": true, "schema": { "type": "boolean" } }, { "name": "subtasks", "in": "query", "description": "Include or exclude subtasks. By default, subtasks are excluded.", "style": "form", "explode": true, "schema": { "type": "boolean" } }, { "name": "statuses", "in": "query", "description": "Filter by statuses. To include closed tasks, use the `include_closed` parameter. \\\n \\\nFor example: \\\n \\\n`?statuses[]=to%20do&statuses[]=in%20progress`", "style": "form", "explode": true, "schema": { "type": "array", "items": { "type": "string" } } }, { "name": "include_closed", "in": "query", "description": "Include or excluse closed tasks. By default, they are excluded.\\\n \\\nTo include closed tasks, use `include_closed: true`.", "style": "form", "explode": true, "schema": { "type": "boolean" } }, { "name": "include_timl", "in": "query", "description": "Include Tasks in Multiple Lists. By default, tasks that exist in multiple lists are excluded from the response.\\\n \\\nTo include tasks that exist in multiple lists, use `include_timl: true`.", "style": "form", "explode": true, "schema": { "type": "boolean" } }, { "name": "assignees", "in": "query", "description": "Filter by Assignees. For example: \\\n \\\n`?assignees[]=1234&assignees[]=5678`", "style": "form", "explode": true, "schema": { "type": "array", "items": { "type": "string" } } }, { "name": "watchers", "in": "query", "description": "Filter by watchers.", "style": "form", "explode": true, "schema": { "type": "array", "items": { "type": "string" } } }, { "name": "tags", "in": "query", "description": "Filter by tags. For example: \\\n \\\n`?tags[]=tag1&tags[]=this%20tag`", "style": "form", "explode": true, "schema": { "type": "array", "items": { "type": "string" } } }, { "name": "due_date_gt", "in": "query", "description": "Filter by due date greater than Unix time in milliseconds.", "style": "form", "explode": true, "schema": { "type": "integer", "contentEncoding": "int32" } }, { "name": "due_date_lt", "in": "query", "description": "Filter by due date less than Unix time in milliseconds.", "style": "form", "explode": true, "schema": { "type": "integer", "contentEncoding": "int32" } }, { "name": "date_created_gt", "in": "query", "description": "Filter by date created greater than Unix time in milliseconds.", "style": "form", "explode": true, "schema": { "type": "integer", "contentEncoding": "int32" } }, { "name": "date_created_lt", "in": "query", "description": "Filter by date created less than Unix time in milliseconds.", "style": "form", "explode": true, "schema": { "type": "integer", "contentEncoding": "int32" } }, { "name": "date_updated_gt", "in": "query", "description": "Filter by date updated greater than Unix time in milliseconds.", "style": "form", "explode": true, "schema": { "type": "integer", "contentEncoding": "int32" } }, { "name": "date_updated_lt", "in": "query", "description": "Filter by date updated less than Unix time in milliseconds.", "style": "form", "explode": true, "schema": { "type": "integer", "contentEncoding": "int32" } }, { "name": "date_done_gt", "in": "query", "description": "Filter by date done greater than Unix time in milliseconds.", "style": "form", "explode": true, "schema": { "type": "integer", "contentEncoding": "int32" } }, { "name": "date_done_lt", "in": "query", "description": "Filter by date done less than Unix time in milliseconds.", "style": "form", "explode": true, "schema": { "type": "integer", "contentEncoding": "int32" } }, { "name": "custom_fields", "in": "query", "description": "Include tasks with specific values in one or more Custom Fields. Custom Relationships are included.\\\n \\\nFor example: `?custom_fields=[{\"field_id\":\"abcdefghi12345678\",\"operator\":\"=\",\"value\":\"1234\"},{\"field_id\":\"jklmnop123456\",\"operator\":\"<\",\"value\":\"5\"}]`\\\n \\\nOnly set Custom Field values display in the `value` property of the `custom_fields` parameter. If you want to include tasks with specific values in only one Custom Field, use `custom_field` instead.\\\n \\\nLearn more about [filtering using Custom Fields.](https://developer.clickup.com/docs/taskfilters)", "style": "form", "explode": true, "schema": { "type": "array", "items": { "type": "string" } } }, { "name": "custom_field", "in": "query", "description": "Include tasks with specific values in only one Custom Field. This Custom Field can be a Custom Relationship.", "style": "form", "explode": true, "schema": { "type": "array", "items": { "type": "string" } } }, { "name": "custom_items", "in": "query", "description": "Filter by custom task types. For example: \\\n \\\n`?custom_items[]=0&custom_items[]=1300` \\\n \\\nIncluding `0` returns tasks. Including `1` returns Milestones. Including any other number returns the custom task type as defined in your Workspace.", "style": "form", "explode": true, "schema": { "type": "array", "items": { "type": "number" } } } ], "responses": { "200": { "description": "", "headers": {}, "content": { "application/json": { "schema": { "title": "GetTasksresponse", "type": "object", "properties": { "tasks": { "type": "array", "items": { "title": "TaskWithMixedOrderIndexType", "type": "object", "properties": { "id": { "type": "string" }, "custom_id": { "type": [ "string", "null" ] }, "custom_item_id": { "type": [ "number", "null" ], "description": "The custom task type ID for this task. A value of `0` represents task type \"Task\".\\\n \\\nTo get a list of available custom task type IDs for your Workspace, use the [Get Custom Task Types endpoint](https://developer.clickup.com/reference/getcustomitems)." }, "name": { "type": "string" }, "text_content": { "type": "string" }, "description": { "type": "string" }, "markdown_description": { "type": "string" }, "status": { "$ref": "#/paths/~1v2~1task~1{task_id}/get/responses/200/content/application~1json/schema/properties/status" }, "orderindex": { "type": [ "string", "number" ] }, "date_created": { "type": "string" }, "date_updated": { "type": "string" }, "date_closed": { "type": [ "string", "null" ] }, "date_done": { "type": [ "string", "null" ] }, "archived": { "type": "boolean" }, "creator": { "$ref": "#/paths/~1v2~1task~1{task_id}/get/responses/200/content/application~1json/schema/properties/creator" }, "assignees": { "type": "array", "items": { "type": "string" }, "description": "" }, "group_assignees": { "type": "array", "items": { "type": "string" }, "description": "" }, "watchers": { "type": "array", "items": { "type": "string" }, "description": "" }, "checklists": { "type": "array", "items": { "type": "string" }, "description": "" }, "tags": { "type": "array", "items": { "type": "string" }, "description": "" }, "parent": { "type": [ "string", "null" ] }, "top_level_parent": { "type": [ "string", "null" ] }, "priority": { "$ref": "#/paths/~1v2~1task~1{task_id}/get/responses/200/content/application~1json/schema/properties/priority" }, "due_date": { "type": [ "string", "null" ] }, "start_date": { "type": [ "string", "null" ] }, "points": { "type": [ "number", "null" ] }, "time_estimate": { "type": [ "string", "null" ] }, "time_spent": { "type": "number", "description": "Time tracked in milliseconds. Only included in the response for tasks with time entries." }, "custom_fields": { "type": "array", "items": { "type": "object", "properties": { "id": { "type": "string" }, "name": { "type": "string" }, "type": { "type": "string", "description": "The Custom Field type." }, "type_config": { "type": "object", "description": "[Configuration options](https://developer.clickup.com/docs/customfields#the-type_config-property) specific to each Custom Field based on the Custom Field type." }, "date_created": { "type": "string" }, "hide_from_guests": { "type": "boolean" }, "required": { "type": "boolean" } } } }, "dependencies": { "type": "array", "items": { "type": "string" }, "description": "" }, "linked_tasks": { "type": "array", "items": { "type": "string" }, "description": "" }, "locations": { "type": "array", "items": { "$ref": "#/paths/~1v2~1task~1{task_id}/get/responses/200/content/application~1json/schema/properties/locations/items" }, "description": "Array of Lists where the task has been added." }, "team_id": { "type": "string" }, "url": { "type": "string" }, "sharing": { "type": "object", "properties": { "public": { "type": "boolean" }, "public_share_expires_on": { "type": [ "string", "null" ] }, "public_fields": { "type": "array", "items": { "type": "string" } }, "token": { "type": [ "string", "null" ] }, "seo_optimized": { "type": "boolean" } } }, "permission_level": { "type": "string" }, "list": { "$ref": "#/paths/~1v2~1task~1{task_id}/get/responses/200/content/application~1json/schema/properties/list" }, "project": { "$ref": "#/paths/~1v2~1task~1{task_id}/get/responses/200/content/application~1json/schema/properties/folder" }, "folder": { "$ref": "#/paths/~1v2~1task~1{task_id}/get/responses/200/content/application~1json/schema/properties/folder" }, "space": { "$ref": "#/paths/~1v2~1task~1{task_id}/get/responses/200/content/application~1json/schema/properties/space" } }, "example": { "id": "9hx", "custom_id": null, "custom_item_id": 0, "name": "Fix login bug", "text_content": "Users are unable to log in when SSO is enabled.", "description": "Users are unable to log in when SSO is enabled.", "status": { "id": "p7001234_FxGmgrnk", "status": "in progress", "color": "#d3d3d3", "orderindex": 1, "type": "custom" }, "orderindex": "1.00000000000000000000000000000000", "date_created": "1567780450202", "date_updated": "1567780450202", "date_closed": null, "date_done": null, "archived": false, "creator": { "id": 183, "username": "Alex Johnson", "color": "#827718", "profilePicture": "https://attachments-public.clickup.com/profilePictures/183_abc.jpg" }, "assignees": [], "group_assignees": [], "watchers": [], "checklists": [], "tags": [], "parent": null, "top_level_parent": null, "priority": { "color": "#f8ae00", "id": "3", "orderindex": "3", "priority": "normal" }, "due_date": "1508369194377", "start_date": null, "points": 3, "time_estimate": "8640000", "time_spent": 7200000, "custom_fields": [ { "id": "d2ab17e0-41d3-4d28-bdbb-f3f0f2c62f8b", "name": "Sprint Goal", "type": "short_text", "type_config": {}, "date_created": "1621915186877", "hide_from_guests": false, "value": "Fix critical auth issues", "value_richtext": "", "required": false }, { "id": "1f3cc395-3448-4264-bedd-590a3b3fa178", "name": "Story Points", "type": "number", "type_config": {}, "date_created": "1627004071219", "hide_from_guests": false, "value": "8", "value_richtext": "", "required": false }, { "id": "f4d2a20d-6759-4420-b897-222dbe2587d4", "name": "Assigned Reviewer", "type": "users", "type_config": { "include_guests": false, "include_team_members": true, "single_user": false }, "date_created": "1618440378816", "hide_from_guests": false, "value": [ { "id": 2772463, "username": "Alex Johnson", "email": "user@company.com", "color": "#FC575E", "initials": "AJ", "profilePicture": null } ], "value_richtext": "", "required": false }, { "id": "b2e4be70-c4d3-4726-985b-46ac25375b28", "name": "Marketing Requirements", "type": "drop_down", "type_config": { "sorting": "manual", "new_drop_down": true, "options": [ { "id": "f8249998-9c0a-4b1d-a8b7-67a072aca05a", "name": "No Marketing Needed", "color": "#b5bcc2", "orderindex": 0 }, { "id": "97704092-e5aa-4005-a87f-677b764d2e4c", "name": "Internal Announcement", "color": "#02BCD4", "orderindex": 1 }, { "id": "c3d4e5f6-a7b8-4c9d-0e1f-a2b3c4d5e6f7", "name": "Release Notes Only", "color": "#7b68ee", "orderindex": 2 }, { "id": "b32b5b93-1839-431e-b9b0-8c4f9de9a84d", "name": "Social Media Post", "color": "#2ecd6f", "orderindex": 3 }, { "id": "87b3c808-a335-4284-a671-e2f9bce66713", "name": "Blog Post", "color": "#f9ae27", "orderindex": 4 }, { "id": "a1c2d3e4-f5a6-7b8c-9d0e-f1a2b3c4d5e6", "name": "Dedicated Campaign with Press", "color": "#e50000", "orderindex": 5 } ] }, "date_created": "1762838079415", "hide_from_guests": false, "value": 2, "value_richtext": "", "required": false } ], "dependencies": [], "linked_tasks": [], "locations": [ { "id": "123456789", "name": "Bug Triage" } ], "team_id": "7002367", "url": "https://app.clickup.com/t/9hx", "sharing": { "public": false, "public_share_expires_on": null, "public_fields": [ "assignees", "priority", "due_date", "content", "comments", "attachments", "customFields", "subtasks", "tags", "checklists", "coverimage" ], "token": null, "seo_optimized": false }, "permission_level": "create", "list": { "id": "15505202", "name": "Sprint Backlog", "access": true }, "project": { "id": "6992470", "name": "Mobile Squad", "hidden": false, "access": true }, "folder": { "id": "6992470", "name": "Mobile Squad", "hidden": false, "access": true }, "space": { "id": "7002367" } } }, "description": "" }, "last_page": { "type": "boolean" } }, "example": { "tasks": [ { "id": "9hx", "custom_id": null, "custom_item_id": 0, "name": "Fix login bug", "text_content": "Users are unable to log in when SSO is enabled.", "description": "Users are unable to log in when SSO is enabled.", "status": { "id": "p7001234_FxGmgrnk", "status": "in progress", "color": "#d3d3d3", "orderindex": 1, "type": "custom" }, "orderindex": "1.00000000000000000000000000000000", "date_created": "1567780450202", "date_updated": "1567780450202", "date_closed": null, "date_done": null, "archived": false, "creator": { "id": 183, "username": "Alex Johnson", "color": "#827718", "profilePicture": "https://attachments-public.clickup.com/profilePictures/183_abc.jpg" }, "assignees": [], "group_assignees": [], "watchers": [], "checklists": [ { "id": "595495f8-4557-41b7-a527-f808664816a0", "task_id": "9hx", "name": "Checklist on a task", "date_created": "1714661812846", "orderindex": "1", "creator": 183, "resolved": 0, "unresolved": 2, "items": [] } ], "tags": [], "parent": null, "top_level_parent": null, "priority": { "color": "#f8ae00", "id": "3", "orderindex": "3", "priority": "normal" }, "due_date": "1508369194377", "start_date": null, "points": 3, "time_estimate": "8640000", "time_spent": 7200000, "custom_fields": [ { "id": "d2ab17e0-41d3-4d28-bdbb-f3f0f2c62f8b", "name": "Sprint Goal", "type": "short_text", "type_config": {}, "date_created": "1621915186877", "hide_from_guests": false, "value": "Fix critical auth issues", "value_richtext": "", "required": false }, { "id": "1f3cc395-3448-4264-bedd-590a3b3fa178", "name": "Story Points", "type": "number", "type_config": {}, "date_created": "1627004071219", "hide_from_guests": false, "value": "8", "value_richtext": "", "required": false }, { "id": "f4d2a20d-6759-4420-b897-222dbe2587d4", "name": "Assigned Reviewer", "type": "users", "type_config": { "include_guests": false, "include_team_members": true, "single_user": false }, "date_created": "1618440378816", "hide_from_guests": false, "value": [ { "id": 2772463, "username": "Alex Johnson", "email": "user@company.com", "color": "#FC575E", "initials": "AJ", "profilePicture": null } ], "value_richtext": "", "required": false }, { "id": "b2e4be70-c4d3-4726-985b-46ac25375b28", "name": "Marketing Requirements", "type": "drop_down", "type_config": { "sorting": "manual", "new_drop_down": true, "options": [ { "id": "f8249998-9c0a-4b1d-a8b7-67a072aca05a", "name": "No Marketing Needed", "color": "#b5bcc2", "orderindex": 0 }, { "id": "97704092-e5aa-4005-a87f-677b764d2e4c", "name": "Internal Announcement", "color": "#02BCD4", "orderindex": 1 }, { "id": "c3d4e5f6-a7b8-4c9d-0e1f-a2b3c4d5e6f7", "name": "Release Notes Only", "color": "#7b68ee", "orderindex": 2 }, { "id": "b32b5b93-1839-431e-b9b0-8c4f9de9a84d", "name": "Social Media Post", "color": "#2ecd6f", "orderindex": 3 }, { "id": "87b3c808-a335-4284-a671-e2f9bce66713", "name": "Blog Post", "color": "#f9ae27", "orderindex": 4 }, { "id": "a1c2d3e4-f5a6-7b8c-9d0e-f1a2b3c4d5e6", "name": "Dedicated Campaign with Press", "color": "#e50000", "orderindex": 5 } ] }, "date_created": "1762838079415", "hide_from_guests": false, "value": 2, "value_richtext": "", "required": false } ], "dependencies": [], "linked_tasks": [], "locations": [ { "id": "123456789", "name": "Bug Triage" } ], "team_id": "7002367", "url": "https://app.clickup.com/t/9hx", "sharing": { "public": false, "public_share_expires_on": null, "public_fields": [ "assignees", "priority", "due_date", "content", "comments", "attachments", "customFields", "subtasks", "tags", "checklists", "coverimage" ], "token": null, "seo_optimized": false }, "permission_level": "create", "list": { "id": "15505202", "name": "Sprint Backlog", "access": true }, "project": { "id": "6992470", "name": "Mobile Squad", "hidden": false, "access": true }, "folder": { "id": "6992470", "name": "Mobile Squad", "hidden": false, "access": true }, "space": { "id": "7002367" } }, { "id": "9hz", "custom_id": null, "custom_item_id": 0, "name": "Update onboarding docs", "text_content": "", "description": "", "status": { "id": "p7002367_HxJmgqni", "status": "to do", "color": "#f8ae00", "orderindex": 0, "type": "open" }, "orderindex": "2.00000000000000000000000000000000", "date_created": "1567780450202", "date_updated": "1567780450202", "date_closed": null, "date_done": null, "archived": false, "creator": { "id": 183, "username": "Alex Johnson", "color": "#827718", "profilePicture": "https://attachments-public.clickup.com/profilePictures/183_abc.jpg" }, "assignees": [], "group_assignees": [], "watchers": [], "checklists": [], "tags": [], "parent": null, "top_level_parent": null, "priority": null, "due_date": null, "start_date": null, "points": null, "time_estimate": null, "custom_fields": [ { "id": "d2ab17e0-41d3-4d28-bdbb-f3f0f2c62f8b", "name": "Sprint Goal", "type": "short_text", "type_config": {}, "date_created": "1621915186877", "hide_from_guests": false, "required": false }, { "id": "1f3cc395-3448-4264-bedd-590a3b3fa178", "name": "Story Points", "type": "number", "type_config": {}, "date_created": "1627004071219", "hide_from_guests": false, "required": false }, { "id": "f4d2a20d-6759-4420-b897-222dbe2587d4", "name": "Assigned Reviewer", "type": "users", "type_config": { "include_guests": false, "include_team_members": true, "single_user": false }, "date_created": "1618440378816", "hide_from_guests": false, "required": false }, { "id": "b2e4be70-c4d3-4726-985b-46ac25375b28", "name": "Marketing Requirements", "type": "drop_down", "type_config": { "sorting": "manual", "new_drop_down": true, "options": [ { "id": "f8249998-9c0a-4b1d-a8b7-67a072aca05a", "name": "No Marketing Needed", "color": "#b5bcc2", "orderindex": 0 }, { "id": "97704092-e5aa-4005-a87f-677b764d2e4c", "name": "Internal Announcement", "color": "#02BCD4", "orderindex": 1 }, { "id": "c3d4e5f6-a7b8-4c9d-0e1f-a2b3c4d5e6f7", "name": "Release Notes Only", "color": "#7b68ee", "orderindex": 2 }, { "id": "b32b5b93-1839-431e-b9b0-8c4f9de9a84d", "name": "Social Media Post", "color": "#2ecd6f", "orderindex": 3 }, { "id": "87b3c808-a335-4284-a671-e2f9bce66713", "name": "Blog Post", "color": "#f9ae27", "orderindex": 4 }, { "id": "a1c2d3e4-f5a6-7b8c-9d0e-f1a2b3c4d5e6", "name": "Dedicated Campaign with Press", "color": "#e50000", "orderindex": 5 } ] }, "date_created": "1762838079415", "hide_from_guests": false, "required": false } ], "dependencies": [], "linked_tasks": [], "locations": [], "team_id": "7002367", "url": "https://app.clickup.com/t/9hz", "sharing": { "public": false, "public_share_expires_on": null, "public_fields": [ "assignees", "priority", "due_date", "content", "comments", "attachments", "customFields", "subtasks", "tags", "checklists", "coverimage" ], "token": null, "seo_optimized": false }, "permission_level": "create", "list": { "id": "15505202", "name": "Sprint Backlog", "access": true }, "project": { "id": "6992470", "name": "Mobile Squad", "hidden": false, "access": true }, "folder": { "id": "6992470", "name": "Mobile Squad", "hidden": false, "access": true }, "space": { "id": "7002367" } } ], "last_page": false } } } } } }, "deprecated": false }, "parameters": [] }, "/v2/task/{task_id}": { "get": { "summary": "Get Task", "tags": [ "Tasks" ], "description": "View information about a task. You can only view task information of tasks you can access. \\\n \\\nTasks with attachments will return an \"attachments\" response. \\\n \\\nDocs attached to a task are not returned.\\\n \\\nThe `custom_fields` array only includes Custom Fields applicable to the task's `custom_item_id`. Use [Get Custom Fields](https://developer.clickup.com/reference/getaccessiblecustomfields) and each field's `applied_objects` to discover which fields apply to which task types.", "operationId": "GetTask", "parameters": [ { "name": "task_id", "in": "path", "description": "", "required": true, "style": "simple", "schema": { "type": "string", "examples": [ "9hz" ] } }, { "name": "custom_task_ids", "in": "query", "description": "If you want to reference a task by its custom task id, this value must be `true`.", "style": "form", "explode": true, "schema": { "type": "boolean", "examples": [ true ] } }, { "name": "team_id", "in": "query", "description": "When the `custom_task_ids` parameter is set to `true`, the Workspace ID must be provided using the `team_id` parameter.\n \\\nFor example: `custom_task_ids=true&team_id=123`.", "style": "form", "explode": true, "schema": { "type": "number", "contentEncoding": "double", "examples": [ 123 ] } }, { "name": "include_subtasks", "in": "query", "description": "Include subtasks, default false", "style": "form", "explode": true, "schema": { "type": "boolean" } }, { "name": "include_markdown_description", "in": "query", "description": "To return task descriptions in Markdown format, use `?include_markdown_description=true`.", "style": "form", "explode": true, "schema": { "type": "boolean", "examples": [ true ] } }, { "name": "custom_fields", "in": "query", "description": "Include tasks with specific values in one or more Custom Fields. Custom Relationships are included.\\\n \\\nFor example: `?custom_fields=[{\"field_id\":\"abcdefghi12345678\",\"operator\":\"=\",\"value\":\"1234\"},{\"field_id\":\"jklmnop123456\",\"operator\":\"<\",\"value\":\"5\"}]`\\\n \\\nOnly set Custom Field values display in the `value` property of the `custom_fields` parameter. If you want to include tasks with specific values in only one Custom Field, use `custom_field` instead.\\\n \\\nLearn more about [filtering using Custom Fields.](https://developer.clickup.com/docs/filtertasks)", "style": "form", "explode": true, "schema": { "type": "array", "items": { "type": "string" } } } ], "responses": { "200": { "description": "", "headers": {}, "content": { "application/json": { "schema": { "title": "GetTaskresponse", "type": "object", "example": { "id": "9hx", "custom_id": null, "custom_item_id": 0, "name": "Fix login bug", "text_content": "Users are unable to log in when SSO is enabled.", "description": "Users are unable to log in when SSO is enabled.", "status": { "id": "p7001234_FxGmgrnk", "status": "in progress", "color": "#d3d3d3", "orderindex": 1, "type": "custom" }, "orderindex": "1.00000000000000000000000000000000", "date_created": "1567780450202", "date_updated": "1567780450202", "date_closed": null, "date_done": null, "archived": false, "creator": { "id": 183, "username": "Alex Johnson", "color": "#827718", "email": "user@company.com", "profilePicture": "https://attachments-public.clickup.com/profilePictures/183_abc.jpg" }, "assignees": [ { "id": 2772463, "username": "Alex Johnson", "color": "#FC575E", "initials": "AJ", "email": "user@company.com", "profilePicture": null } ], "group_assignees": [], "watchers": [ { "id": 2772463, "username": "Alex Johnson", "color": "#FC575E", "initials": "AJ", "email": "user@company.com", "profilePicture": null } ], "checklists": [], "tags": [ { "name": "bug", "tag_fg": "#EA80FC", "tag_bg": "#EA80FC", "creator": 183 } ], "parent": null, "top_level_parent": null, "priority": { "color": "#f8ae00", "id": "3", "orderindex": "3", "priority": "normal" }, "due_date": "1508369194377", "start_date": null, "points": 3, "time_estimate": "8640000", "time_spent": 0, "custom_fields": [ { "id": "d2ab17e0-41d3-4d28-bdbb-f3f0f2c62f8b", "name": "Sprint Goal", "type": "short_text", "type_config": {}, "date_created": "1621915186877", "hide_from_guests": false, "value": "Fix critical auth issues", "value_richtext": "", "required": false }, { "id": "1f3cc395-3448-4264-bedd-590a3b3fa178", "name": "Story Points", "type": "number", "type_config": {}, "date_created": "1627004071219", "hide_from_guests": false, "value": "8", "value_richtext": "", "required": false }, { "id": "f4d2a20d-6759-4420-b897-222dbe2587d4", "name": "Assigned Reviewer", "type": "users", "type_config": { "include_guests": false, "include_team_members": true, "single_user": false }, "date_created": "1618440378816", "hide_from_guests": false, "value": [ { "id": 2772463, "username": "Alex Johnson", "email": "user@company.com", "color": "#FC575E", "initials": "AJ", "profilePicture": null } ], "value_richtext": "", "required": false }, { "id": "b2e4be70-c4d3-4726-985b-46ac25375b28", "name": "Marketing Requirements", "type": "drop_down", "type_config": { "sorting": "manual", "new_drop_down": true, "options": [ { "id": "f8249998-9c0a-4b1d-a8b7-67a072aca05a", "name": "No Marketing Needed", "color": "#b5bcc2", "orderindex": 0 }, { "id": "97704092-e5aa-4005-a87f-677b764d2e4c", "name": "Internal Announcement", "color": "#02BCD4", "orderindex": 1 }, { "id": "c3d4e5f6-a7b8-4c9d-0e1f-a2b3c4d5e6f7", "name": "Release Notes Only", "color": "#7b68ee", "orderindex": 2 }, { "id": "b32b5b93-1839-431e-b9b0-8c4f9de9a84d", "name": "Social Media Post", "color": "#2ecd6f", "orderindex": 3 }, { "id": "87b3c808-a335-4284-a671-e2f9bce66713", "name": "Blog Post", "color": "#f9ae27", "orderindex": 4 }, { "id": "a1c2d3e4-f5a6-7b8c-9d0e-f1a2b3c4d5e6", "name": "Dedicated Campaign with Press", "color": "#e50000", "orderindex": 5 } ] }, "date_created": "1762838079415", "hide_from_guests": false, "value": 2, "value_richtext": "", "required": false } ], "dependencies": [ { "task_id": "9hx", "depends_on": "8gx", "type": 1, "date_created": "1675970762803", "userid": "183", "workspace_id": "1234567", "chain_id": null } ], "linked_tasks": [], "locations": [], "team_id": "1234567", "url": "https://app.clickup.com/t/9hx", "sharing": { "public": false, "public_share_expires_on": null, "public_fields": [ "assignees", "priority", "due_date", "content", "comments", "attachments", "customFields", "subtasks", "tags", "checklists", "coverimage" ], "token": null, "seo_optimized": false }, "permission_level": "create", "list": { "id": "15505202", "name": "Sprint Backlog", "access": true }, "project": { "id": "6992470", "name": "Mobile Squad", "hidden": false, "access": true }, "folder": { "id": "6992470", "name": "Mobile Squad", "hidden": false, "access": true }, "space": { "id": "7002367" }, "attachments": [ { "id": "62447c77-2086-4cda-b274-f53eccf0547b.txt", "date": 1711570108374, "title": "error-logs.txt", "type": 1, "source": 1, "version": 0, "extension": "txt", "thumbnail_small": null, "thumbnail_medium": null, "thumbnail_large": null, "is_folder": null, "mimetype": "text/plain", "hidden": false, "parent_id": "9hx", "size": 140970, "total_comments": 0, "resolved_comments": 0, "user": { "id": 183, "username": "Alex Johnson", "initials": "AJ", "email": "user@company.com", "color": "#827718", "profilePicture": "https://attachments-public.clickup.com/profilePictures/183_abc.jpg" }, "deleted": false, "orientation": null, "url": "https://t123456.p.clickup-attachments.com/t123456/62447c77-2086-4cda-b274-f53eccf0547b/error-logs.txt", "email_data": null, "url_w_query": "https://t123456.p.clickup-attachments.com/t123456/62447c77-2086-4cda-b274-f53eccf0547b/error-logs.txt?view=open", "url_w_host": "https://t123456.p.clickup-attachments.com/t123456/62447c77-2086-4cda-b274-f53eccf0547b/error-logs.txt" } ] }, "properties": { "id": { "type": "string" }, "custom_id": { "type": [ "string", "null" ] }, "custom_item_id": { "type": [ "number", "null" ], "description": "The custom task type ID for this task. A value of `0` represents task type \"Task\".\\\n \\\nTo get a list of available custom task type IDs for your Workspace, use the [Get Custom Task Types endpoint](https://developer.clickup.com/reference/getcustomitems)." }, "name": { "type": "string" }, "text_content": { "type": "string" }, "description": { "type": "string" }, "markdown_description": { "type": "string", "description": "Only returned if `include_markdown_description=true` is passed as a query parameter." }, "status": { "title": "Status", "type": "object", "properties": { "id": { "type": "string" }, "status": { "type": "string" }, "color": { "type": "string" }, "orderindex": { "type": "integer", "contentEncoding": "int32" }, "type": { "type": "string" } }, "examples": [ { "id": "p7001234_FxGmgrnk", "status": "in progress", "color": "#d3d3d3", "orderindex": 1, "type": "custom" } ] }, "orderindex": { "type": "string" }, "date_created": { "type": "string" }, "date_updated": { "type": "string" }, "date_closed": { "type": [ "string", "null" ] }, "date_done": { "type": [ "string", "null" ] }, "archived": { "type": "boolean" }, "creator": { "title": "Creator", "type": "object", "properties": { "id": { "type": "integer", "contentEncoding": "int32" }, "username": { "type": "string" }, "color": { "type": "string" }, "email": { "type": "string" }, "profilePicture": { "type": [ "string", "null" ] } }, "examples": [ { "id": 183, "username": "Alex Johnson", "color": "#827718", "email": "user@company.com", "profilePicture": "https://attachments-public.clickup.com/profilePictures/183_abc.jpg" } ] }, "assignees": { "type": "array", "items": { "type": "object", "properties": { "id": { "type": "integer" }, "username": { "type": "string" }, "color": { "type": "string" }, "initials": { "type": "string" }, "email": { "type": "string" }, "profilePicture": { "type": [ "string", "null" ] } } }, "description": "" }, "group_assignees": { "type": "array", "items": { "type": "object" }, "description": "" }, "watchers": { "type": "array", "items": { "type": "object", "properties": { "id": { "type": "integer" }, "username": { "type": "string" }, "color": { "type": "string" }, "initials": { "type": "string" }, "email": { "type": "string" }, "profilePicture": { "type": [ "string", "null" ] } } }, "description": "" }, "checklists": { "type": "array", "items": { "type": "object" }, "description": "" }, "tags": { "type": "array", "items": { "type": "object", "properties": { "name": { "type": "string" }, "tag_fg": { "type": "string" }, "tag_bg": { "type": "string" }, "creator": { "type": "integer" } } }, "description": "" }, "parent": { "type": [ "string", "null" ] }, "top_level_parent": { "type": [ "string", "null" ] }, "priority": { "title": "Priority", "type": "object", "nullable": true, "properties": { "color": { "type": "string" }, "id": { "type": "string" }, "orderindex": { "type": "string" }, "priority": { "type": "string" } }, "examples": [ { "color": "#f8ae00", "id": "3", "orderindex": "3", "priority": "normal" } ] }, "due_date": { "type": [ "string", "null" ] }, "start_date": { "type": [ "string", "null" ] }, "points": { "type": [ "number", "null" ] }, "time_estimate": { "type": [ "number", "null" ] }, "time_spent": { "type": [ "number", "null" ] }, "custom_fields": { "type": "array", "items": { "title": "CustomFields8", "type": "object", "examples": [ { "id": "d2ab17e0-41d3-4d28-bdbb-f3f0f2c62f8b", "name": "Sprint Goal", "type": "short_text", "type_config": {}, "date_created": "1621915186877", "hide_from_guests": false, "value": "Improve onboarding flow", "value_richtext": "", "required": false }, { "id": "1f3cc395-3448-4264-bedd-590a3b3fa178", "name": "Story Points", "type": "number", "type_config": {}, "date_created": "1627004071219", "hide_from_guests": false, "value": "8", "value_richtext": "", "required": false }, { "id": "f4d2a20d-6759-4420-b897-222dbe2587d4", "name": "Assigned Reviewer", "type": "users", "type_config": { "include_guests": false, "include_team_members": true, "single_user": false }, "date_created": "1618440378816", "hide_from_guests": false, "value": [ { "id": 2772463, "username": "Alex Johnson", "email": "user@company.com", "color": "#FC575E", "initials": "AJ", "profilePicture": null } ], "value_richtext": "", "required": false }, { "id": "b2e4be70-c4d3-4726-985b-46ac25375b28", "name": "Marketing Requirements", "type": "drop_down", "type_config": { "sorting": "manual", "new_drop_down": true, "options": [ { "id": "f8249998-9c0a-4b1d-a8b7-67a072aca05a", "name": "No Marketing Needed", "color": "#b5bcc2", "orderindex": 0 }, { "id": "97704092-e5aa-4005-a87f-677b764d2e4c", "name": "Internal Announcement", "color": "#02BCD4", "orderindex": 1 }, { "id": "c3d4e5f6-a7b8-4c9d-0e1f-a2b3c4d5e6f7", "name": "Release Notes Only", "color": "#7b68ee", "orderindex": 2 }, { "id": "b32b5b93-1839-431e-b9b0-8c4f9de9a84d", "name": "Social Media Post", "color": "#2ecd6f", "orderindex": 3 }, { "id": "87b3c808-a335-4284-a671-e2f9bce66713", "name": "Blog Post", "color": "#f9ae27", "orderindex": 4 }, { "id": "a1c2d3e4-f5a6-7b8c-9d0e-f1a2b3c4d5e6", "name": "Dedicated Campaign with Press", "color": "#e50000", "orderindex": 5 } ] }, "date_created": "1762838079415", "hide_from_guests": false, "value": 2, "value_richtext": "", "required": false }, { "id": "0aef6ee9-3c54-49e7-aa1a-e981845c773a", "name": "Team", "type": "labels", "type_config": { "sorting": "manual", "options": [ { "id": "2245c581-0fb7-4bba-b5f9-d40e421ab2d2", "label": "Frontend", "color": "#bf55ec", "orderindex": 0 }, { "id": "6992d629-f336-4e3a-87a5-6fd0738d91dd", "label": "Backend", "color": "#04A9F4", "orderindex": 1 } ] }, "date_created": "1614656692549", "hide_from_guests": false, "value": [ "978d9762-34f7-4b6e-8e1b-0ac3216deb39", "cd82b57c-7511-4c9d-a25f-0c8d7db807d4" ], "value_richtext": "", "required": false }, { "id": "be43f58e-989e-4233-9f25-27584f094b74", "name": "Office Location", "type": "location", "type_config": {}, "date_created": "1617765143523", "hide_from_guests": false, "value": { "location": { "lat": 47.306988, "lng": -122.5263212 }, "place_id": "ChIJs79efm1TkFQRJjrP-xr8u0M", "formatted_address": "5400 N Pearl St, Tacoma, WA 98407, USA" }, "value_richtext": "", "required": false } ], "properties": { "id": { "type": "string" }, "name": { "type": "string" }, "type": { "type": "string" }, "type_config": { "type": "object", "description": "The configuration of the Custom Field. The structure of this object varies depending on the [Custom Field type](ref:docs/customfields)." }, "date_created": { "type": "string" }, "hide_from_guests": { "type": "boolean" }, "value": { "description": "The value of the Custom Field. The structure of this value varies depending on the [Custom Field type](https://developer.clickup.com/docs/customfields)." }, "value_richtext": { "type": "string" }, "value_markdown": { "type": "string" }, "required": { "type": "boolean" } } }, "description": "Custom Fields applicable to the task's `custom_item_id`. Fields scoped to other custom task types are excluded. Fields without a value may still appear with their definition." }, "dependencies": { "type": "array", "items": { "type": "object", "properties": { "task_id": { "type": "string" }, "depends_on": { "type": "string" }, "type": { "type": "integer" }, "date_created": { "type": "string" }, "userid": { "type": "string" }, "workspace_id": { "type": "string" }, "chain_id": { "type": [ "string", "null" ] } } }, "description": "" }, "linked_tasks": { "type": "array", "items": { "type": "object" }, "description": "" }, "locations": { "type": "array", "items": { "title": "ListLocation", "type": "object", "properties": { "id": { "type": "string", "description": "The ID of the List where the task has been added." }, "name": { "type": "string", "description": "The name of the List where the task has been added." } }, "examples": [ { "id": "123456789", "name": "Secondary List" } ] }, "description": "Array of Lists where the task has been added." }, "team_id": { "type": "string" }, "url": { "type": "string" }, "sharing": { "type": "object", "properties": { "public": { "type": "boolean" }, "public_share_expires_on": { "type": [ "string", "null" ] }, "public_fields": { "type": "array", "items": { "type": "string" } }, "token": { "type": [ "string", "null" ] }, "seo_optimized": { "type": "boolean" } } }, "permission_level": { "type": "string" }, "list": { "title": "List", "type": "object", "properties": { "id": { "type": "string" }, "name": { "type": "string" }, "access": { "type": "boolean" } }, "examples": [ { "id": "15505202", "name": "Sprint Backlog", "access": true } ] }, "project": { "$ref": "#/paths/~1v2~1task~1{task_id}/get/responses/200/content/application~1json/schema/properties/folder" }, "folder": { "title": "Folder", "type": "object", "properties": { "id": { "type": "string" }, "name": { "type": "string" }, "hidden": { "type": "boolean" }, "access": { "type": "boolean" } }, "examples": [ { "id": "6992470", "name": "Mobile Squad", "hidden": false, "access": true } ] }, "space": { "title": "Space", "type": "object", "properties": { "id": { "type": "string" } }, "examples": [ { "id": "7002367" } ] }, "subtasks": { "type": "array", "description": "Only returned if `include_subtasks=true` is passed as a query parameter.", "items": { "title": "Subtask", "type": "object", "properties": { "id": { "type": "string" }, "custom_item_id": { "type": [ "number", "null" ] }, "name": { "type": "string" }, "status": { "type": "object", "properties": { "status": { "type": "string" }, "orderindex": { "type": "integer" }, "color": { "type": "string" }, "type": { "type": "string" } } }, "orderindex": { "type": "string" }, "date_created": { "type": "string" }, "date_updated": { "type": "string" }, "date_closed": { "type": [ "string", "null" ] }, "date_done": { "type": [ "string", "null" ] }, "archived": { "type": "boolean" }, "creator": { "$ref": "#/paths/~1v2~1task~1{task_id}/get/responses/200/content/application~1json/schema/properties/creator" }, "assignees": { "type": "array", "items": { "type": "object", "properties": { "id": { "type": "integer" }, "username": { "type": "string" }, "color": { "type": "string" }, "initials": { "type": "string" }, "email": { "type": "string" }, "profilePicture": { "type": [ "string", "null" ] } } } }, "group_assignees": { "type": "array", "items": { "type": "object" } }, "watchers": { "type": "array", "items": { "type": "object" } }, "checklists": { "type": "array", "items": { "type": "object" } }, "tags": { "type": "array", "items": { "type": "object" } }, "parent": { "type": [ "string", "null" ] }, "top_level_parent": { "type": [ "string", "null" ] }, "due_date": { "type": [ "string", "null" ] }, "start_date": { "type": [ "string", "null" ] }, "points": { "type": [ "number", "null" ] }, "time_estimate": { "type": [ "number", "null" ] }, "time_spent": { "type": [ "number", "null" ] }, "custom_fields": { "type": "array", "items": { "$ref": "#/paths/~1v2~1task~1{task_id}/get/responses/200/content/application~1json/schema/properties/custom_fields/items" } }, "dependencies": { "type": "array", "items": { "type": "object" } }, "linked_tasks": { "type": "array", "items": { "type": "object" } }, "locations": { "type": "array", "items": { "type": "object" } }, "url": { "type": "string" } }, "example": { "id": "86d2m1awy", "custom_item_id": 0, "name": "Reproduce the issue on staging", "status": { "status": "to do", "orderindex": 0, "color": "#f8ae00", "type": "open" }, "orderindex": "237672022.00000000000000000000000000000000", "date_created": "1775848408603", "date_updated": "1775848408603", "date_closed": null, "date_done": null, "archived": false, "creator": { "id": 183, "username": "Alex Johnson", "color": "#595d66", "email": "user@company.com", "profilePicture": null }, "assignees": [], "group_assignees": [], "watchers": [], "checklists": [], "tags": [], "parent": "9hx", "top_level_parent": "9hx", "due_date": null, "start_date": null, "points": null, "time_estimate": null, "time_spent": 0, "custom_fields": [], "dependencies": [], "linked_tasks": [], "locations": [], "url": "https://app.clickup.com/t/86d2m1awy" } } }, "attachments": { "type": "array", "items": { "type": "object", "properties": { "id": { "type": "string" }, "date": { "type": "integer", "format": "int64" }, "title": { "type": "string" }, "type": { "type": "integer" }, "source": { "type": "integer" }, "version": { "type": "integer" }, "extension": { "type": "string" }, "thumbnail_small": { "type": "string" }, "thumbnail_medium": { "type": "string" }, "thumbnail_large": { "type": "string" }, "is_folder": { "type": "boolean" }, "mimetype": { "type": "string" }, "hidden": { "type": "boolean" }, "parent_id": { "type": "string" }, "size": { "type": "integer", "format": "int64" }, "total_comments": { "type": "integer" }, "resolved_comments": { "type": "integer" }, "user": { "title": "User2", "type": "object", "properties": { "id": { "type": "integer", "contentEncoding": "int32" }, "username": { "type": "string" }, "initials": { "type": "string" }, "email": { "type": "string" }, "color": { "type": "string" }, "profilePicture": { "type": "string" } }, "examples": [ { "id": 183, "username": "John Doe", "initials": "JD", "email": "user@company.com", "color": "#827718", "profilePicture": "https://attachments-public.clickup.com/profilePictures/183_abc.jpg" } ] }, "deleted": { "type": "boolean" }, "orientation": { "type": "string" }, "url": { "type": "string" }, "email_data": { "type": "object" }, "url_w_query": { "type": "string" }, "url_w_host": { "type": "string" } } } } } } } } } }, "deprecated": false }, "parameters": [] } }, "components": { "securitySchemes": { "Authorization_Token": { "name": "Authorization", "type": "apiKey", "in": "header", "description": "API token required for authentication. Two types of tokens are supported:\n**Personal API Key** Obtain from ClickUp's settings page under 'Apps' and add it to the header as `Authorization: pk_...`\n**OAuth2 Access Token** Generated through the OAuth2 flow and add it to the header as `Authorization: Bearer {access_token}`" } } }, "security": [ { "Authorization_Token": [] } ], "tags": [ { "name": "Tasks" } ] } ```