Nothing Found

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 , or dueDate .
  • 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 like yesterday .
  • 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 or OR operators, and groups themselves can be nested and combined in the same way.

The overall structure works as follows:

  1. 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"}]}
  2. 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.
  3. Apply Logical Operators Between Groups : The filter_group_ops array specifies how to combine these groups using logical operators like AND and OR . For example, ["OR", "AND"] indicates that within the first group, filters are combined using OR , and then the result is combined with the second group using AND .

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:

Copy
Copied
{
    "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:

Copy
Copied
{
    "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 [].

Copy
Copied
{
    "field": "archived",
    "op": "EQ",
    "values": []
}

Assignee

Filter tasks by assignee.

Operators:

  • ANY , ALL , NOT ANY , NOT ALL

Values: Array of user IDs.

Copy
Copied
{
    "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
Copy
Copied
{
    "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):

Copy
Copied
{
    "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:

  • To filter by status type, use "type": "{status_type_name}" , eg "type": "active" .
  • To filter by status name, use "{status_name}" , eg "in progress" .

Example:

Copy
Copied
{
    "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.

Copy
Copied
{
    "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.

Copy
Copied
{
    "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) and NOT (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), and LTE (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:

Copy
Copied
{
    "field": "cf_ec49d70b-72e1-40c2-b04c-b0f728499f28",
    "op": "EQ",
    "values": [null]
}
ClickUp Logo
Login