Tasks

For more details on how to work with custom fields please refer to Working with custom fields guide.

The Task object represents a task within the project management system.

You can find out more about tasks in our Help documentation: Tasks and task lists

Task can be one of two types:

  • milestone
  • task

Following diagram shows tasks in our data hierarchy:

ProjectFolderTask listTaskCommentsSubtasksTodos

For Task dependencies please refer to TaskDependency endpoint documentation

Attributes

after string
Parameter `filter`

Return tasks created on or after this date.
assignee person
Response

The person assigned to this task.
assignee_id any of: Option 1b198c27-78b1-47a2-b7e3-12bb70512568, Option 91f1cbac-fae8-444e-98b0-72b3fb7c6e62
Request Parameter `filter`

Filter by assigned person (also matches open to-do assignees).
Show child attributes
assignee_name object
Parameter `sort`

Filter by assigned person (also matches open to-do assignees).
attachment_ids array of any of: Option 5ff306cc-530c-4111-9698-50039c9bbcb9, Option 923fd7ef-ea33-4068-866b-e73bf5d67c08
Request

Files attached to this task.
Show child attributes
attachments array of attachment
Response

Files attached to this task.
before string
Parameter `filter`

Return tasks created on or before this date.
billable_time integer
Response Parameter `filter` Parameter `sort`

Total billable hours tracked on this task (time + correction for billable services, zero for non-billable).
blocking_dependency_count integer
Response

Number of tasks this task is blocking from starting.
board_name string
Parameter `sort`

Filter by folder name (text search).
board_position object
Parameter `sort`

Sort position of this task within its board (folder).
board_status integer
Parameter `filter` Enum

The open/closed status of the task list (board) this task belongs to.

Enum Values (2 values)

  • 1
    Open
  • 2
    Closed
bookable_after string
Parameter `filter`

Filter tasks to those bookable after this date.
bookable_before string
Parameter `filter`

Filter tasks to those bookable before this date.
booked_time integer
Response Parameter `filter`

Total time booked against this task through resource scheduling, in minutes. Aggregated from the task's service bookings.
bookings_count integer
Response

Number of scheduled bookings referencing this task.
closed boolean
Response

Whether the task is closed (derived from closed_at).
closed_after string
Parameter `filter`

Return tasks closed on or after this date.
closed_at string
Response Parameter `filter` Parameter `sort`

Timestamp when the task was closed, or null if still open.
closed_before string
Parameter `filter`

Return tasks closed on or before this date.
company_id any of: Option 9d244cb5-de18-48af-ac4f-9c5d6df53036, Option 1b7b8457-b6bd-42b6-9625-834971390e3c
Parameter `filter`

Filter by client company (via the task's project).
Show child attributes
company_name object
Parameter `sort`

Filter by client company (via the task's project).
created_at string
Response Parameter `filter` Parameter `sort`

Timestamp when the task was created.
creation_method_id integer
Response Enum

How the task was created (e.g. manually, via automation, via email).

Enum Values (4 values)

  • 1
    Native created
  • 2
    Created through email
  • 3
    Created through integration
  • 4
    Slack
creator person
Response

The person who created this task.
creator_id any of: Option b47f2e01-c426-414b-9bba-9e512b251421, Option 043c8db1-85d9-48f8-a149-f744e1dda4e6
Parameter `filter`

ID of the person who created this task.
Show child attributes
creator_name object
Parameter `sort`

The name of the person who created this task.
custom_field_attachments array of attachment
Response

Files uploaded to file-type custom fields on this task.
custom_field_people array of person
Response

People referenced in person-type custom fields on this task.
custom_fields object
Response Request Parameter `filter` Parameter `sort`

Custom field values set on this task.
date_range string
Parameter `filter`

Filter tasks overlapping a date range (for timeline/Gantt views).
deleted_at string
Response

Timestamp if the task was soft-deleted, null otherwise.
dependency_type integer
Parameter `filter` Enum

Filter by dependency type: blocking, waiting on, or linked.

Enum Values (3 values)

  • 1
    Blocking
  • 2
    Waiting on
  • 3
    Linked
description string
Response Request Parameter `filter`

[DESCRIPTION]
due_date string
Response Request Parameter `filter` Parameter `sort`

Date by which the task should be completed.
due_date_after string
Parameter `filter`

Return tasks due on or after this date.
due_date_before string
Parameter `filter`

Return tasks due on or before this date.
due_date_new string
Parameter `filter`

Return tasks due on this exact date.
due_date_on string
Parameter `filter`

Return tasks due on this exact date.
due_time string
Response Request

Time of day for the due date deadline (HH:MM format).
email_key string
Response

Unique key for creating comments on this task via email.
folder_id any of: Option 643d5267-95d4-48d0-9f47-9460be867b67, Option da424be8-8839-4861-9477-08ffa89742ce
Parameter `filter`

Filter by folder ID (alias for board_id).
Show child attributes
folder_name string
Parameter `filter` Parameter `sort`

Filter by folder name (alias for board_name).
folder_position object
Parameter `sort`

Sort position of this task within its folder.
folder_status integer
Parameter `filter` Enum

Filter by whether the folder is active or archived (alias for board_status).

Enum Values (2 values)

  • 1
    Open
  • 2
    Closed
full_query string
Parameter `filter`

Full-text search across task fields.
future_booked_time integer
Response Parameter `filter`

Time booked against this task that is scheduled from today onward, in minutes — the forward-looking portion of booked_time.
fuzzy_dates string
Parameter `filter`

Fuzzy date matching across task date fields.
fuzzy_people any of: Option ad26f7eb-6787-4cad-bfc6-1afc31218b26, Option f3f0648a-935e-4de2-b62d-df09f3ea6331
Parameter `filter`

Fuzzy match by people related to the task.
Show child attributes
id any of: Option 710c022e-d381-4f9c-890a-82ff7af70bec, Option d2cd3973-4e4d-4001-9cf9-0cc4ca346dbe
Parameter `filter` Parameter `sort`

The unique identifier of this task.
Show child attributes
initial_estimate integer
Response Request Parameter `filter` Parameter `sort`

Originally forecasted time needed to complete the task, in minutes.
jump_query string
Parameter `filter`

Quick jump search by task name or number.
last_activity string
Parameter `filter` Parameter `sort`

Timestamp of the most recent activity on this task.
last_activity_after string
Parameter `filter`

Return tasks with last activity after this date.
last_activity_at string
Response Parameter `sort`

Timestamp of the most recent activity on this task.
last_activity_before string
Parameter `filter`

Return tasks with last activity before this date.
last_actor person
Response

The last person who made changes to this task.
last_actor_id any of: Option 322309d9-1c05-44fd-920f-ed846752c560, Option 604e04f3-0c1d-4158-b74f-e4d88f93e5e4
Parameter `filter`

ID of the person who last performed an activity on this task.
Show child attributes
last_actor_name object
Parameter `sort`

The name of the person who last performed an activity on this task.
left_to_schedule_time integer
Parameter `filter`

[DESCRIPTION]
level integer
Response Parameter `filter` Enum

Depth of the task in its subtask tree. A task at level 2 can't have subtasks.

Enum Values (3 values)

  • 0
    Root task
  • 1
    Subtask
  • 2
    Subtask of a subtask
linked_dependency_count integer
Response

Number of tasks linked to this one (informational, no blocking).
net_unplanned_time integer
Parameter `filter`

[DESCRIPTION]
number string
Response Parameter `sort`

Short numeric identifier (alias for task_number).
open_subtask_count integer
Response

Number of unclosed subtasks.
open_todo_count integer
Response

Number of uncompleted to-do items.
organization organization
Response

The organization this task belongs to.
overdue_status integer
Parameter `filter` Enum

Filter by whether the task is overdue (past due date).

Enum Values (2 values)

  • 1
    Not overdue
  • 2
    Overdue
parent_task task
Response

The parent task if this is a subtask.
parent_task_id any of: Option 5e2d6605-1f3a-454e-8d19-9add299f9e06, Option 59242bc2-3eec-40b6-9853-f2de56a03731
Request Parameter `filter`

Filter by parent task (to find subtasks of a specific task).
Show child attributes
person_type integer
Parameter `filter`

Filter by parent/subtask distinction.
placeholder_usages array of placeholder usage
Response

[DESCRIPTION]
placement integer
Response Parameter `sort`

Sort position of this task within its task list.
private boolean
Response Request

Whether this task is visible only to project members (not shared via public links).
project project
Response

The project this task belongs to.
project_id any of: Option af090883-1a44-4c05-8f1d-1907e1b853f4, Option b2ac2f26-d2e6-4dc8-b5d6-c4f63f018161
Request Parameter `filter`

ID of the project (workspace) this task belongs to.
Show child attributes
project_manager_id any of: Option 92cf5d62-390e-448b-b95a-fcc6d2ee8c1f, Option 6efb4eb3-1014-4210-b62c-ea67fcd88538
Parameter `filter`

Filter by the project's responsible person.
Show child attributes
project_name object
Parameter `sort`

The name of the project this task belongs to.
project_type integer
Parameter `filter` Enum

Filter by project type: internal (overhead) or client (billable).

Enum Values (2 values)

  • 1
    Internal project
  • 2
    Client project
public_access boolean
Parameter `filter`

Filter by task privacy (deprecated — use private filter instead).
query string
Parameter `filter`

Quick search matching task title and number.
query_extended string
Parameter `filter`

Extended search matching title, number, and description.
remaining_time integer
Response Request Parameter `filter` Parameter `sort`

Current projection of time still needed, decreases as time is tracked or can be adjusted manually.
repeated_task task
Response

The recurring schedule configuration if this task repeats.
repeating boolean
Parameter `filter`

Whether this task is part of a repeating schedule.
repeat_on_date string
Response Request

Specific date for date-based recurring tasks.
repeat_on_interval integer
Response Request

How frequently the task repeats (e.g. daily, weekly, monthly).
repeat_on_monthday integer
Response Request

Day of the month for monthly recurring tasks.
repeat_on_weekday array of integer
Response Request

Array of ISO weekday IDs (1..7) on which a recurring task fires. Example: [1, 3, 5] for Mondays, Wednesdays, and Fridays.
repeat_origin_id integer
Response

ID of the original task that spawned this recurring instance.
repeat_schedule_id integer
Response Request Enum

ID of the repeat schedule if this task recurs on a regular interval.

Enum Values (4 values)

  • 1
    Daily
  • 2
    Weekly
  • 3
    Monthly
  • 4
    Yearly
root_task task
Response

The root task of the subtask tree, if this is a subtask.
root_task_id any of: Option 4e90727f-a9f5-46c3-8789-1774112b9553, Option d3035b53-8bdb-4fd5-b49f-86ebae766c03
Parameter `filter`

Filter by root task to get every subtask in its tree at any depth. The root task itself isn't returned.
Show child attributes
service service
Response

The budget service linked to this task for time tracking and billing.
service_id any of: Option bad40d51-1961-48a2-ace5-76b59da6c437, Option 7c978e0a-e089-4775-8274-e55cc9f1ce50
Request Parameter `filter`

ID of the service (billing point) this task is linked to.
Show child attributes
skip_reposition boolean
Request

If true, skips reordering of other tasks when placing this one.
start_date string
Response Request Parameter `filter` Parameter `sort`

Date when work on the task is planned to begin.
start_date_after string
Parameter `filter`

Return tasks starting on or after this date.
start_date_before string
Parameter `filter`

Return tasks starting on or before this date.
status integer
Parameter `filter` Enum

Filter by open (1) or closed (2) status.

Enum Values (2 values)

  • 1
    Active
  • 2
    Archived
subscriber_id any of: Option b526aa08-efac-4def-b5ab-5072b37d5e57, Option 77f0197f-9304-4260-a587-b2dcd342c100
Parameter `filter`

ID of a person who is subscribed to notifications for this task.
Show child attributes
subscriber_ids array of any of: Option ef66e8a5-5af3-47c1-a9fd-a11beef6dd33, Option 03453b0d-f95a-4884-912d-c0a14806383b
Request

Array of IDs of people subscribed to notifications for this task.
Show child attributes
subtask boolean
Parameter `filter`

Whether this task is a subtask of another task.
subtask_count integer
Response

Number of direct subtasks under this task.
subtask_placement integer
Response

Sort position among sibling subtasks under the parent task.
subtasks array of task
Response

[DESCRIPTION]
tag_list array of string
Response Request

Tags applied to this task.
tags string
Parameter `filter`

Tags applied to this task.
task_dependencies array of task dependency
Response

[DESCRIPTION]
task_dependency_count integer
Response

Total number of dependency relationships on this task.
task_list task list
Response

The task list this task belongs to within a folder.
task_list_id any of: Option b2ee60e6-6e4b-40ac-94b2-f53ea5b8af83, Option b012a327-b32d-4dab-897c-07049048de30
Request Parameter `filter`

ID of the task list (milestone) this task belongs to.
Show child attributes
task_list_name string
Parameter `filter` Parameter `sort`

Filter by task list name (text search).
task_list_position object
Parameter `sort`

Sort position of this task within its task list.
task_list_status integer
Parameter `filter` Enum

The open/closed status of the task list this task belongs to.

Enum Values (2 values)

  • 1
    Open
  • 2
    Closed
task_number string
Response Parameter `filter` Parameter `sort`

Unique number identifying a task within the organization.
task_type integer
Parameter `filter` Enum

Filter by parent/subtask distinction.

Enum Values (2 values)

  • 1
    Parent task
  • 2
    Subtask
template string
Parameter `filter`

Return only template tasks.
template_id any of: Option 6bc5da84-ecff-4c35-a011-11a5208052c7, Option a3b4cfed-5cc9-4130-bb2e-e01fb9cbc413
Parameter `filter`

ID of the template this task was created from.
Show child attributes
template_object template
Response

The template this task was created from, if applicable.
title string
Response Request Parameter `filter` Parameter `sort`

Descriptive name of the task.
todo_assignee_ids array of string
Response

IDs of people assigned to open to-do items on this task.
todo_count integer
Response

Total number of to-do checklist items on this task.
todos array of todo
Response

[DESCRIPTION]
trackable_by_person_id any of: Option 92710551-c9b3-4d35-93f0-48dac7da90c6, Option 61f416ba-d189-4ad5-aac9-3f1682915640
Parameter `filter`

Filter tasks to those trackable by the specified person, based on restricted tracking settings.
Show child attributes
type_id integer
Response Request Parameter `filter` Enum

Task type: regular task, subtask, or milestone.

Enum Values (2 values)

  • 1
    Task
  • 3
    Key task
updated_at string
Response Parameter `filter` Parameter `sort`

Timestamp when the task was last modified.
waiting_on_dependency_count integer
Response

Number of tasks this task is waiting on before it can proceed.
worked_time integer
Response Parameter `filter` Parameter `sort`

Total time tracked on this task across all time entries, in minutes.
workflow_id any of: Option 5c4eac3c-21ed-4248-97d9-98ec3cab0a5d, Option 8aa6068c-385b-43b2-a73d-0ffdc1473dcb
Parameter `filter`

ID of the workflow this task's status belongs to.
Show child attributes
workflow_status workflow status
Response

Current workflow status of this task (e.g. 'To Do', 'In Progress', 'Done').
workflow_status_category_id integer
Parameter `filter` Enum

Filter by status category: not started (1), started (2), or closed (3).

Enum Values (3 values)

  • 1
    Not started
  • 2
    Started
  • 3
    Closed
workflow_status_id any of: Option c093afb0-093b-4445-9426-7731ef4f8669, Option ff07b221-0b51-47ae-997f-a78d5430aaa1
Request Parameter `filter`

ID of the workflow status currently assigned to this task.
Show child attributes
workflow_status_name object
Parameter `sort`

Current workflow status of this task (e.g. 'To Do', 'In Progress', 'Done').
workflow_status_position object
Parameter `sort`

Sort position of the workflow status within its workflow.

Examples

Loading example

Operations

GET /api/v2/tasks
Get tasks
POST /api/v2/tasks
Create a task
POST /api/v2/tasks/copy
Copies a task
DELETE /api/v2/tasks/{id}
Deletes a task
GET /api/v2/tasks/{id}
Gets a task
PATCH /api/v2/tasks/{id}
Update a task
PATCH /api/v2/tasks/{id}/move_dependent
Moves a task and its dependent tasks by a given number of working days
PATCH /api/v2/tasks/{id}/reposition
Repositions a task