How to Use the ClickUp Shared Hierarchy API

The ClickUp Shared Hierarchy API lets you quickly discover every list, folder, space, task, and subtask that has been shared with a specific user anywhere in your workspace. This guide explains how to call the endpoint, filter the results, and use the response to power internal tools, dashboards, or integrations.

Understanding the ClickUp Shared Hierarchy Endpoint

The Shared Hierarchy is a REST endpoint that returns all hierarchy locations and tasks shared with a user, and it works across your entire ClickUp workspace. You can sort, filter, and page through the results using simple query parameters.

The base endpoint for this feature is:

GET /shared-hierarchy

It returns a JSON payload describing matching spaces, folders, lists, tasks, and subtasks, plus metadata that helps you build navigation and search features.

Prerequisites for Calling the ClickUp API

Before you can work with the Shared Hierarchy resource, make sure you have:

• A ClickUp workspace with at least one member and some shared items.
• A valid ClickUp API token with the necessary read permissions.
• Basic familiarity with HTTP requests (for example, using curl, Postman, or a server-side library).

You also need at least one user in mind whose shared items you want to query, because the request requires user information in the query string.

Required Parameters for the ClickUp Shared Hierarchy

The Shared Hierarchy endpoint has two key parameters. These are typically passed as query parameters:

• user_id: Identifies the user whose shared hierarchy you want to retrieve.
• team_id or equivalent workspace identifier: Tells the API which workspace to search in for that user.

Consult the official API reference at ClickUp Shared Hierarchy documentation for the current, exact parameter names and allowed values.

How to Make a ClickUp Shared Hierarchy Request

Follow these steps to issue a basic request and start exploring shared items.

Step 1: Set Your ClickUp Authorization Header

Every call to the Shared Hierarchy endpoint must include your API token in the request headers. The pattern typically looks like this:

Authorization: <YOUR_CLICKUP_API_TOKEN>

Make sure you keep this token secure and never expose it in client-side code or public repositories.

Step 2: Build the ClickUp Query String

Next, construct the query string with the required user information and any optional filters. At a minimum, you will include:

• user_id to target the user.
• A workspace identifier so the API knows which ClickUp team to search.

You can then extend the query string with optional filters for pagination, sorting, or scoping to particular hierarchy types.

Step 3: Send the Request to ClickUp

With the header and query parameters ready, send a GET request to the Shared Hierarchy endpoint. For example, using a generic pattern:

GET https://api.clickup.com/api/v2/shared-hierarchy?user_id=<USER_ID>&team_id=<TEAM_ID>

If the request is successful, the ClickUp API returns a JSON response describing the shared folders, lists, tasks, and other matching items.

Working With the ClickUp Shared Hierarchy Response

The response payload groups results into different hierarchy levels and includes identifiers and metadata that you can use to build workspace maps and user-centric dashboards.

Main Structures in the ClickUp Response

Typical fields you will see in the JSON response include:

• spaces: A collection of spaces that are shared with the user.
• folders: Folders inside those spaces the user can access.
• lists: Lists that are directly or indirectly shared.
• tasks and subtasks: Work items shared with the user, including nested subtasks.
• pagination or cursor info: Data you use to fetch additional pages of results.

Depending on how you structure your request, you might receive all shared items at once, or you might need to page through multiple responses.

Common Use Cases for the ClickUp Shared Hierarchy

Once you have the response, you can use it for a variety of workflow enhancements, including:

• Generating a custom “Shared with me” view for any user.
• Auditing which ClickUp lists or folders are shared with specific team members.
• Feeding analytics dashboards with cross-space sharing data.
• Building AI or LLM tools that understand a user’s current shared tasks.

Because the endpoint spans the whole workspace, it is ideal for global reporting and access review tools.

Filtering and Paginating ClickUp Shared Results

Large ClickUp workspaces may return many shared items, so you should apply filters and pagination whenever possible.

Pagination Options in ClickUp

The Shared Hierarchy endpoint uses traditional pagination or cursor-based pagination (depending on the current API version and configuration). Review the response fields for:

• A page number or cursor token for the next page.
• A flag indicating whether there are more results to fetch.

To get the next page, include the provided token or increment the page parameter in your next request.

Filtering by ClickUp Hierarchy Type

If you only care about a subset of the hierarchy, use filters to limit the response. For example, you may want only tasks and subtasks, or only lists shared directly with the user. Common strategies include:

• Filtering on specific hierarchy levels (spaces, folders, lists, tasks).
• Filtering on status, archived state, or permission type if available.
• Combining filters with pagination to keep each response small and efficient.

By filtering precisely, you reduce response size, improve performance, and simplify post-processing in your application.

Best Practices for Using the ClickUp Shared Hierarchy

To build robust integrations on top of the Shared Hierarchy data, keep these guidelines in mind.

Optimize ClickUp API Performance

• Cache non-sensitive results where appropriate to avoid unnecessary repeated calls.
• Use pagination parameters rather than requesting the maximum size in every call.
• Schedule heavy reporting queries during off-peak hours for your team.

Secure Your ClickUp Data

• Store API tokens in environment variables or secure vaults.
• Never embed tokens directly inside public front-end code.
• Respect the permissions returned by the API and avoid exposing data a user should not see.

Combine ClickUp Shared Hierarchy With Other Endpoints

You can enrich the Shared Hierarchy data by calling additional endpoints for details about tasks, custom fields, or attachments. A typical pattern is:

1. Call the Shared Hierarchy endpoint to get all locations shared with a user.
2. Extract the relevant IDs for tasks or lists.
3. Call dedicated detail endpoints to obtain full task metadata or custom fields.

This approach keeps the initial query light while still giving you the power to drill deeper when necessary.

Next Steps for Advanced ClickUp Integrations

After you have mastered the basics of the Shared Hierarchy endpoint, you can design richer solutions, including AI-powered assistants and advanced reporting layers on top of your ClickUp data. For strategic advice on scaling workspace integrations and automation, you can explore additional resources and implementation guidance from analytics and automation specialists such as Consultevo.

To stay aligned with the latest changes and parameter options, always refer back to the official ClickUp Shared Hierarchy reference before deploying your integration to production.