Filter views

You can filter tasks in a view using the ClickUp API.

Operator

The op property of the filters object stands for operator and determines how multiple filter criteria work together.

The available values for this property are AND and OR.

Search by task name and description

The search property of the filters object is a filter for task name, description, and matching Custom Field text.

Searching by name, description, and Custom Field text is only available when creating a view.

The search filter always uses the AND operator when combined with any other filter, regardless of the op property value.

The following example creates a view that's filtered to show tasks with "zebra" in the task name, description, or Custom Fields.

{
    "filters": {
        "op": "AND",
        "fields": [],
        "search": "zebra",
        "show_closed": false
    }
}

Show closed

The show_closed property is a filter to show or hide closed tasks. By default, close tasks are not shown (false).

You can also use the status filter, however, the show_closed filter always uses the AND operator when combined with any other filter, regardless of the op property value.

Filter fields

The filters.fields array is where you will include most your filters.

Every object in this array will always follow this format:

{
    "field": "field name",
    "op": "op name",
    "values": []
}

Archived

To filter for archived tasks, use the archived field.

Operators:

• EQ
• NOT

Values: The values array is ignored for this filter, but must be included as [].

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

Assignee

You can filter tasks by assignee.

Operators:

• ANY
• ALL
• NOT ANY
• NOT ALL

Values: Include an array of user ids.

{
    "field": "assignee",
    "op": "ANY",
    "values": [182, 183]
}

Priority

You can filter tasks by priority.

Operators:

• EQ
• NOT

Values: Include an array of priority values using the following values:

• -1: No priority
• 1: Urgent priority
• 2: High priority
• 3: Normal priority
• 4: Low priority

{
    "field": "priority",
    "op": "EQ",
    "values": ["4", "-1"]
}

Date filters

You can filter by various date fields available in ClickUp. All supported date fields use the same operators and value format.

Standard date fields

You can use these standard task date fields:

• Due date: dueDate
• Start date: startDate
• Date created: dateCreated
• Date updated: dateUpdated
• Date closed: dateClosed

Date Custom Fields

To use a Date Custom Field, use the Custom Field name which uses the format cf_{{field_id}}.

For example, if the id of your Date Custom Field is ec49d70b-72e1-40c2-b04c-b0f728499f28, then the field name would be cf_ec49d70b-72e1-40c2-b04c-b0f728499f28.

Filter operators

Operators:

• EQ
• NOT

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

You can filter by status.

Operators:

• EQ
• NOT

Values: Use the "type": "x" format to target status types, such as active, done, or closed.

Otherwise, pass an array of status names as strings.

• "type": "active"
• "type": "done" }
• "type": "closed" }
• "in progress"
• "ready for review"

{
    "field": "status",
    "op": "EQ",
    "values": ["in progress", "ready for review", { "type": "done" }]
}

Tag

You can filter using task Tags.

Operators:

• ANY
• ALL
• NOT ANY
• NOT ALL

Values: Include an array of tags names.

{
    "field": "tag",
    "op": "ANY",
    "values": ["tag 1", "tag 2"]
}

Recurring

You can filter tasks based on whether or not they are recurring tasks.

Operators:

• EQ (only includes recurring tasks)
• NOT (only includes non-recurring tasks)

Values: The values array is ignored for this filter but must be included.

{
    "field": "recurring",
    "op": "EQ",
    "values": []
}

Custom Fields

To filter by a Custom Field, you must include the field name using the format cf_{{field_id}}.

For example, if the id of your Custom Field is ec49d70b-72e1-40c2-b04c-b0f728499f28, then the field name would be cf_ec49d70b-72e1-40c2-b04c-b0f728499f28.

You can find the id of the Custom Fields that are available for a given List using the following endpoints:

• Get Accessible Custom Fields endpoint
• Get Task
• Get Tasks
• Get Filtered team Tasks endpoint

Operators:

• All Custom Field types can use the filter operators EQ and NOT.
• Additionally, you can use the operators GT, GTE, LT, and LTE for number and currency Custom Fields.
• For Date Custom Fields, you can use the Date operators .

Values: The type of values you can add to the values array depend on the type of Custom Field that you are filtering by.

For example, for a number field you would pass [12], but to indicate a drop down option, you would pass the ID, such as ["435562d0-0b35-4cfe-9726-1c4baf8d1c44"].

Filter by is set and is not set

For any Custom Field, you can filter by is set and is not set by passing: { "op": "IS SET", "values": [null] } (does not equal null) { "op": "IS NOT SET", "values": [null] } (equals null).

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