Ordering and Limiting Requests

Ordering and Limiting Lists of Tasks

Order Parameter

You can request that a list of tasks be returned in a particular order. Specify an order parameter whose value is one of the following:

Order parameter

Description

earliest_start

default - returns the items with the earliest earliest_start first

updated_at

returns the most recently updated_at items first

Invalid values return an error response

Limit Parameter

You can request that no more than a certain number of tasks be returned. Specify a limit parameter whose value is an integer greater than zero. Invalid values return an error response.

Ordering of Items in Containers

Every item has a global_priority attribute.

Packaged items additionally have a global_package_priority attribute. For scheduling purposes, this overrides the item’s global_priority.

The values of these attributes are arrays of numbers specifying relative positions in the tree. The values of these attributes are comparable or sortable, but otherwise arbitrary; e.g. you cannot infer the quantity of a project’s items from the global_priority of its lowest priority item.

Two items with the same parent will have identical values for global_priority in all but the last position in the array, and the value in this last position indicates their relative order within the container itself (lesser value first, greater value second). The same principles apply to two items packaged in the same package and the values of their global_package_priority attributes.

📘

Limiting and Ordering Treeitems

Please note that the limit and order parameters are not available on /treeitems endpoint; they can only be applied on concrete item types such as /tasks, /events, /projects, etc.