How to Filter Tasks with the ClickUp API

Developers can use the ClickUp API to fetch and filter tasks with precision, making it easier to power dashboards, reports, and integrations that depend on accurate task data.

This how-to guide walks you step by step through the Get Filtered Team Tasks endpoint, explaining parameters, common filters, and practical usage patterns.

Understanding the ClickUp filtered team tasks endpoint

The Get Filtered Team Tasks endpoint lets you retrieve tasks for a specific team (Workspace) while applying a wide range of filters.

Key characteristics of this ClickUp endpoint include:

HTTP method: GET
Base path: /api/v2/team/{team_id}/task
Authentication: personal token or OAuth2 bearer token in the Authorization header
Response: a JSON list of tasks with metadata and pagination info

By combining multiple query parameters, you can build a precise filtered view similar to what you see in the ClickUp interface, but consumable by your own applications.

Prerequisites for working with the ClickUp API

Before you start calling this endpoint, make sure you have the following prepared:

A ClickUp Workspace (team) you can access
A valid API token or OAuth2 access token
Your team_id value
A REST client or HTTP library (for example, cURL, Postman, or code using fetch, axios, or similar)

For strategy, architecture, or implementation help around APIs and productivity platforms, you can also consult specialists at Consultevo.

Step 1: Authenticate to the ClickUp API

Every request to the ClickUp tasks endpoint must include an Authorization header with your token.

Basic pattern:

GET https://api.clickup.com/api/v2/team/{team_id}/task
Authorization: Bearer YOUR_ACCESS_TOKEN

Replace {team_id} with the numeric Workspace ID, and YOUR_ACCESS_TOKEN with your personal or OAuth2 token.

Obtaining your token in ClickUp

While the detailed token retrieval process is documented in the main API docs, the general flow is:

Log in to your ClickUp account.
Open your account settings or API settings area.
Generate a personal API token, or configure an OAuth2 app.
Store the token securely; you will use it in all API calls.

Step 2: Build the base ClickUp request

Start with a minimal request that just validates your access to the endpoint.

GET https://api.clickup.com/api/v2/team/{team_id}/task?include_closed=true

Common query parameters you might start with:

include_closed: whether to include closed tasks
page: for pagination (starting at 0)
order_by: how tasks are sorted (for example, by created or updated)

Once you confirm that your base request returns results, you can layer on more filters.

Step 3: Filter ClickUp tasks by space, folder, and list

To limit the scope of results, use location-based filters. These are especially useful for large Workspaces.

Common location parameters include:

space_ids: comma-separated list of space IDs
folder_ids: comma-separated list of folder IDs
list_ids: comma-separated list of list IDs

Example request filtering by a couple of lists:

GET https://api.clickup.com/api/v2/team/{team_id}/task?list_ids=123,456&include_closed=false

By limiting the scope, you reduce payload size and keep your integration focused on the ClickUp areas that matter most.

Step 4: Filter ClickUp tasks by status and assignee

Filtering by task status and assignee allows you to pull only actionable items or user-specific views.

Using status filters in ClickUp

You can filter tasks by one or more statuses:

statuses: comma-separated status names (for example, to do,in progress,review)
include_closed: whether tasks with closed statuses are included

Example URL snippet:

?statuses=to%20do,in%20progress&include_closed=false

Using assignee filters in ClickUp

For user-focused dashboards, use assignee parameters:

assignees: comma-separated user IDs
include_closed: to include or exclude closed tasks

Example combining filters:

GET https://api.clickup.com/api/v2/team/{team_id}/task?assignees=111111,222222&statuses=in%20progress&include_closed=false

This pattern is ideal for building ClickUp-style “My work” or team workload views within your own systems.

Step 5: Filter ClickUp tasks by dates

The endpoint supports several date-related filters. All values are sent as Unix timestamps in milliseconds.

Common date parameters include:

due_date_gt / due_date_lt: filter by due date range
date_created_gt / date_created_lt: filter by creation time
date_updated_gt / date_updated_lt: filter by last update time

Example: tasks due within a specific window:

GET https://api.clickup.com/api/v2/team/{team_id}/task?due_date_gt=1704067200000&due_date_lt=1706745600000

This enables reporting that aligns ClickUp tasks with OKR cycles, sprints, or billing periods.

Step 6: Filter ClickUp tasks by custom fields

One of the most powerful capabilities of this endpoint is filtering by custom fields. Custom fields in ClickUp can represent priorities, client names, budgets, or any domain-specific data you use.

How custom field filters work

Custom field filters rely on two parts:

The custom field ID (an internal identifier)
The filter operator and value, expressed in the query string

Typical pattern:

custom_fields[{field_id}][operator]={operator}&custom_fields[{field_id}][value]={value}

Depending on the field type, supported operators can include:

is / is_not
gt / gte
lt / lte
between

By combining several custom field filters, you can reproduce very granular ClickUp views through the API.

Step 7: Sort and paginate ClickUp task results

Once you have filters defined, you may need sorting and pagination to control how you process data.

Sorting options

Key parameters include:

order_by: field to sort by (for example, created, updated, due_date)
reverse: reverse sort order when set to true

Example sorting by most recently updated:

?order_by=updated&reverse=true

Pagination options

Because ClickUp can hold a large number of tasks, pagination is crucial:

page: the page index, usually starting at 0
limit (if exposed for this endpoint): number of tasks per page

The response payload includes data to help you determine whether additional pages exist, so you can iterate until you have retrieved all matching tasks.

Step 8: Handle the ClickUp API response

When you call the endpoint, you receive a JSON object containing:

An array of task objects with properties such as id, name, status, assignees, and custom fields
Pagination or metadata fields

Typical handling flow:

Parse the JSON response.
Iterate over the tasks array.
Map each task to your internal data model.
Store or display the results in your application or reporting layer.

Because this mirrors how views work inside ClickUp, you can closely align in-app filters with your external integrations.

Best practices for using the ClickUp filtered tasks endpoint

To keep your integration reliable and efficient, consider these practices:

Limit the scope with space, folder, and list filters instead of querying the entire team.
Use date filters to avoid repeatedly fetching historical tasks.
Cache results where appropriate to reduce repeated calls against the same filters.
Log request parameters and responses to assist with debugging.
Respect rate limits described in the broader ClickUp API documentation.

Refer back to the official ClickUp filtered team tasks reference whenever you need the latest list of supported parameters and response fields.

Next steps

With the filtered team tasks endpoint, you can power sophisticated reports, dashboards, and automations that stay in sync with what users see in ClickUp itself.

Next, you can:

Combine this endpoint with task creation and update endpoints to build full workflow automation.
Align ClickUp views with external BI tools or custom portals.
Implement scheduled jobs that export filtered tasks for analytics or backups.

By carefully selecting filters and parameters, you can turn raw ClickUp task data into focused, actionable information in any system you build.

Need Help With ClickUp?

If you want expert help building, automating, or scaling your ClickUp workspace, work with ConsultEvo — trusted ClickUp Solution Partners.

Get Help

“`

How to Filter Tasks in ClickUp