Filter Views
Filter tasks in a view via API.
The filtering system in your project management software is designed to help you refine your task list by specifying detailed criteria based on task attributes. This system is structured around four key components:
fields, operators, values, and groups.
-
Fields
represent the task attributes you want to filter by, such as
status
,tag
, ordueDate
. -
Operators
define the type of comparison to perform on the field. Common operators include:
-
EQ
(equals): Checks if the field exactly matches the specified value(s). -
ANY
: Checks if the field contains any of the specified values. -
Other operators can include relational comparisons like
LT
(less than),GT
(greater than), or functions likeyesterday
.
-
- Values are the specific criteria you're filtering for. These can be single values or arrays of values, depending on the operator and field.
-
Groups
allow you to combine multiple filters using logical operators to create complex queries. Filters within a group can be combined using
AND
orOR
operators, and groups themselves can be nested and combined in the same way.
The overall structure works as follows:
-
Define Individual Filters
: Each filter is an object that specifies a field, an operator, and one or more values. For example:
-
{field: "status", op: "EQ", values: ["product backlog", "product review"]}
-
{field: "tag", op: "ANY", values: ["#bug"]}
-
{field: "dueDate", op: "EQ", values: [{op: "yesterday"}]}
-
-
Organize Filters into Groups
: Filters are grouped to determine the order of operations. Groups are arrays of filter indices that reference the individual filters you've defined. For instance,
[[0, 1], [2]]
creates two groups: the first contains filters 0 and 1, and the second contains filter 2. -
Apply Logical Operators Between Groups
: The
filter_group_ops
array specifies how to combine these groups using logical operators likeAND
andOR
. For example,["OR", "AND"]
indicates that within the first group, filters are combined usingOR
, and then the result is combined with the second group usingAND
.
By structuring your filters this way, you can create sophisticated queries to find tasks that meet complex criteria, such as tasks that are either in the "product backlog" or "product review" status OR have the tag "#bug", AND are due yesterday.
Operator
The op
property specifies how filter criteria combine. Available values:
-
AND
-
OR
Search by Task Name and Description
The search
property filters by task name, description, and Custom Field text. This filter is only available when creating a view. Search is implemented with basic string matching.
Search is performed on the filtered results, regardless of the op
value provided for the search operator. Logically (all filters) AND search
.
Example:
{
"filters": {
"op": "AND",
"fields": [],
"search": "zebra",
"show_closed": false
}
}
Show Closed
The show_closed
property hides closed tasks by default (false
). It always uses the AND
operator when combined with other filters.
Filter Fields
The filters.fields
array holds most of the filter criteria. Each object follows this format:
{
"field": "field name",
"op": "op name",
"values": []
}
Archived
To filter archived tasks, use the archived
field.
Operators:
-
EQ
-
NOT
Values: The values array is ignored but must be included as []
.
{
"field": "archived",
"op": "EQ",
"values": []
}
Assignee
Filter tasks by assignee.
Operators:
-
ANY
,ALL
,NOT ANY
,NOT ALL
Values: Array of user IDs.
{
"field": "assignee",
"op": "ANY",
"values": [182, 183]
}
Priority
Filter tasks by priority.
Operators:
-
EQ
,NOT
Values:
-
-1
: No priority -
1
: Urgent -
2
: High -
3
: Normal -
4
: Low
{
"field": "priority",
"op": "EQ",
"values": ["4", "-1"]
}
Date Filters
Filter by standard or custom date fields.
Standard Date Fields
Available fields for all tasks:
-
Due date:
dueDate
-
Start date:
startDate
-
Date created:
dateCreated
-
Date updated:
dateUpdated
-
Date done:
dateDone
-
Date closed:
dateClosed
Date Custom Fields
Use the format cf_{{field_id}}
to reference any custom fields.
Date Operators
-
EQ
,NOT
-
Dynamic date values:
today
,yesterday
,overdue
,thisweek
, etc.
Values:
Due date values are dynamic values, which allow you to specify values such as today
or overdue
and query due dates without actually setting a specific timestamp.
Each value is an object with a descriptive operator (op
) property and sometimes one or more reference values.
- "op": "today"
- "op": "yesterday"
- "op": "tomorrow"
- "op": "next7" (next seven days)
- "op": "last7" (last seven days)
- "op": "overdue"
- "op": "earlier" (today and earlier)
- "op": "thisweek"
- "op": "thismonth"
- "op": "lastmonth"
- "op": "eq", "dueDate": 1579240800000 (exact date)
- "op": "ls", "dueDate": 1579240800000 (before date)
- "op": "gt", "dueDate": 1579240800000 (after date)
- "op": "ra", "dueDate": 1579240800000, "startDate": 1579068000000 (date range)
- "op": "notNull" (any date)
- "op": "null" (no date)
The below example will include tasks where the due date is set (equals not null):
{
"field": "dueDate",
"op": "EQ",
"values": [{ "op": "notNull" }]
}
Status
Filter tasks by status or status type.
Status types contain multiple statuses. For example: active
, done
, or closed
.
Operators:
-
EQ
,NOT
Values:
-
Filter by status type use
"type": "{status_type_name}"
, eg"type": "active"
. -
Filter by status name use
"{status_name}"
, eg"in progress"
.
Example:
{
"field": "status",
"op": "EQ",
"values": ["in progress", "{ 'type': 'done' }"]
}
Tag
Filter tasks by tags.
Operators:
-
ANY
,ALL
,NOT ANY
,NOT ALL
Values: Array of tag names.
{
"field": "tag",
"op": "ANY",
"values": ["tag 1", "tag 2"]
}
Recurring
Filter based on whether tasks are recurring.
Operators:
-
EQ
(recurring),NOT
(non-recurring)
Values: The values array is ignored but must be included.
{
"field": "recurring",
"op": "EQ",
"values": []
}
Custom Fields
Use the format cf_{{field_id}}
to filter by Custom Fields.
Find available Custom Fields with these endpoints:
Operators:
-
All Custom Field types support the
EQ
(equals) andNOT
(not equals) filter operators. -
For number and currency Custom Fields, you can also use the
GT
(greater than),GTE
(greater than or equal to),LT
(less than), andLTE
(less than or equal to) operators. - For Date Custom Fields, refer to the available Date operators .
Filter by Set/Not Set
Use SET
and NOT SET
to determine if value is null
.
Use:
-
"op": "IS SET"
-
"op": "IS NOT SET"
Pass [null]
into the values
key.
Example:
{
"field": "cf_ec49d70b-72e1-40c2-b04c-b0f728499f28",
"op": "EQ",
"values": [null]
}