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.

Example