tasks.tasks.getList
Returns a list of tasks corresponding to specified filtering conditions.
Parameters
-
hash
GET
Hash denoting the main task filtering condition.
Examples of hashes:
- id/42: search for the task with ID = 42,
- number/10.20: search for the task with the “10.20” number in the “project_id.task_number” format,
- all: return all tasks without filtering,
- inbox: return incoming tasks for the current user,
- outbox: return outgoing tasks for the current user,
- favorites: return tasks from the “Watching” list,
- urgent: return urgent tasks,
- unassigned: return tasks without assignment to a user,
- assigned/12: return tasks assigned to the user whose ID is 12,
- creator/12: return tasks created by the user whose ID is 12,
- scope/1: return tasks belonging to the milestone with the ID = 1,
- project/2: return the tasks of the project with the ID = 2,
- status/inprogress: return the tasks which have not been closed,
- status/done: return closed tasks,
- status/3: return tasks in the status with the ID = 3,
- search/qwerty: search tasks by query “qwerty”,
- tag/bug: search tasks by tag “bug”. -
offset
GET
Offset relative to the filtered list of tasks. Offset 0 means to return the task list from the very beginning.
-
limit
GET
Optional
Maximum number of tasks which must be returned. If not specified then default value 30 is used.
-
filters
GET
Optional
Additional filtering parameter taking into account the value specified in the “hash” parameter. Examples: 'assigned_contact_id=1' (return tasks assigned to the user whose ID is 1), 'milestone_id=5' (return tasks which belong to the milestone with the ID = 1), 'status_id=-1' (return tasks with the status ID = -1).
-
since
GET
Optional
Timestamp to return only tasks updated after the specified date and time.
-
order
GET
Optional
Sort order. Available values: 'priority', 'oldest', 'newest', 'due'. If not specified then the following values are used by default: for value 'outbox' specified in the “hash” parameter — 'oldest'; for value 'status' specified in the “hash” parameter and 'status_id=-1' specified in the “filters” parameter — 'newest'; in other cases the default sorting value is 'priority'.
-
format
GET
Optional
Sets response format. Available options:
json
(default),xml
.
Return value
Array with the following keys:
- data[]['id'] int Task ID.
- data[]['name'] string Task name.
- data[]['text'] string Task description.
- data[]['text_stripped'] string Task description without HTML tags, truncated to maximum 256 characters.
- data[]['assign_log_id'] int|null ID of the latest log entry about the task assignment to a user.
- data[]['assigned_contact'] array|null Information about the user, to which the task has been assigned, with the following keys:
- data[]['assigned_contact']['id'] int User ID.
- data[]['assigned_contact']['name'] string User name.
- data[]['assigned_contact']['photo_url'] string URL of a 96x96 pixels large user image.
- data[]['assignment_creator_contact'] array|null Information about the user, who assigned the task, with the following keys:
- data[]['assignment_creator_contact']['id'] int User ID.
- data[]['assignment_creator_contact']['name'] string User name.
- data[]['assignment_creator_contact']['photo_url'] string URL of a 96x96 pixels large user image.
- data[]['attachments'] array The list of files attached to the task. Each array item is an array with the following keys:
- data[]['attachments'][]['id'] int File ID.
- data[]['attachments'][]['code'] string Random file code.
- data[]['attachments'][]['contact'] array The properties of the user, who has added the task, as an array with the following keys:
- data[]['attachments'][]['contact']['id'] int User ID.
- data[]['attachments'][]['contact']['name'] string User name.
- data[]['attachments'][]['contact']['photo_url'] string URL of a 96x96 pixels large user image.
- data[]['attachments'][]['create_datetime'] string Date and time of the task creation in the ISO 8601 format.
- data[]['attachments'][]['download_url'] string File URL.
- data[]['attachments'][]['ext'] string File name extension.
- data[]['attachments'][]['is_image'] bool Flag denoting whether the file contains an image.
- data[]['attachments'][]['log_id'] int ID of the entry about the added task in the user actions log.
- data[]['attachments'][]['name'] string File name.
- data[]['attachments'][]['preview_url'] string URL of the file’s preview image.
- data[]['attachments'][]['size'] int File size in bytes.
- data[]['comment_log_id'] int|null ID of the latest log record about an added comment.
- data[]['contact_id'] int|null ID of the user who was the last to execute an action on the task.
- data[]['create_contact'] array Information about the user, who has added the task, as an array with the following keys:
- data[]['create_contact']['id'] int User ID.
- data[]['create_contact']['name'] string User name.
- data[]['create_contact']['photo_url'] string URL of a 96x96 pixels large user image.
- data[]['create_datetime'] string Date and time of the task adding in the ISO 8601 format.
- data[]['due_date'] date|null Deadline date.
- data[]['favorite'] bool Flag denoting whether the task is in the “Watching” list of the current user.
- data[]['favorite_unread'] bool Flag denoting whether the task is in the “Watching” list of the current user and is marked for them as unread.
- data[]['hidden_timestamp'] int|null Timestamp of the date and time of sending the task to the archive.
- data[]['log'] array The list of actions in the task log. Each list item is an array with the following keys with the following keys:
- data[]['log'][]['action'] string Action performed an a task.
- data[]['log'][]['after_status_id'] int ID of the status in which the task had been before the action was executed.
- data[]['log'][]['assigned_contact'] array Information about the user, to which the task was assigned, with the following keys:
- data[]['log'][]['assigned_contact']['id'] int User ID.
- data[]['log'][]['assigned_contact']['name'] string User name.
- data[]['log'][]['assigned_contact']['is_me'] bool Flag denoting whether the action was executed by the current user.
- data[]['log'][]['assigned_contact']['photo_url'] string URL of a 96x96 pixels large user image.
- data[]['log'][]['assignment_changed'] bool Flag denoting whether the task was assigned to another user when the action was executed.
- data[]['log'][]['attachments'] array The list of files during the action execution. Each array item is an array with the following keys:
- data[]['log'][]['attachments'][]['id'] int File ID.
- data[]['log'][]['attachments'][]['code'] string Random file code.
- data[]['log'][]['attachments'][]['contact'] array The properties of the user, who executed the action, as an array with the following keys:
- data[]['log'][]['attachments'][]['contact']['id'] int User ID.
- data[]['log'][]['attachments'][]['contact']['is_me'] bool Flag denoting whether the action was executed by the current user.
- data[]['log'][]['attachments'][]['contact']['name'] string User name.
- data[]['log'][]['attachments'][]['contact']['photo_url'] string URL of a 96x96 pixels large user image.
- data[]['log'][]['attachments'][]['create_datetime'] string Date and time of the action execution in the ISO 8601 format.
- data[]['log'][]['attachments'][]['download_url'] string File URL.
- data[]['log'][]['attachments'][]['ext'] string File name extension.
- data[]['log'][]['attachments'][]['is_image'] bool Flag denoting whether the file contains an image.
- data[]['log'][]['attachments'][]['log_id'] int ID of the entry about the added comment in the user actions log.
- data[]['log'][]['attachments'][]['name'] string File name.
- data[]['log'][]['attachments'][]['preview_url'] string URL of the file’s preview image.
- data[]['log'][]['attachments'][]['size'] int File size in bytes.
- data[]['log'][]['before_status_id'] int ID of the status in which the task had been before the action execution.
- data[]['log'][]['contact'] array The properties of the user, who executed the action, with the following keys:
- data[]['log'][]['contact']['id'] int User ID.
- data[]['log'][]['contact']['name'] string User name.
- data[]['log'][]['contact']['photo_url'] string URL of a 96x96 pixels large user image.
- data[]['log'][]['create_datetime'] string Date and time of the action execution in the ISO 8601 format.
- data[]['log'][]['project_id'] int ID of the project to which the task belongs.
- data[]['log'][]['status_changed'] bool Flag denoting whether the task status was changed during the action execution.
- data[]['log'][]['task_id'] int Task ID.
- data[]['log'][]['task_name'] string Task name.
- data[]['log'][]['task_number'] string Task’s number within its project.
- data[]['log'][]['text'] string Text entered by a user during the action execution.
- data[]['log'][]['text_stripped'] string Entered text without HTML tags, truncated to maximum 256 characters.
- data[]['milestone_id'] int|null Milestone ID.
- data[]['next_status_id'] int ID of the next status according to the settings of the project to which the task belongs.
- data[]['number'] int Task’s number within its project.
- data[]['priority'] int Task priority.
- data[]['project_id'] int Project ID.
- data[]['publicLinks'] array The list of URLs of public links to the task.
- data[]['status_id'] int Status ID.
- data[]['tags'] array The list of tags linked to the task. Each list item is an array with the following keys with the following keys:
- data[]['tags'][]['id'] int Tag ID.
- data[]['tags'][]['name'] string Tag name.
- data[]['update_datetime'] string Date and time of the task update.
- data[]['uuid'] string Unique task identifier.