ClickUp Folder API Guide

/ ClickUp / By

How to Get a Folder with the ClickUp API

The ClickUp API lets you retrieve detailed information about a single folder so you can power custom integrations, reporting, and automation. This guide walks you through every step to call the Get Folder endpoint successfully and interpret the response.

Understanding the ClickUp Get Folder Endpoint

The Get Folder endpoint returns information about one specific folder by its unique ID. It uses a simple REST structure and supports standard HTTPS and JSON.

The documented endpoint is:

GET https://api.clickup.com/api/v2/folder/{folder_id}

Use this endpoint when you already know the folder ID and you want to fetch its data, including its name, status, list contents, and other key properties.

Prerequisites for Using the ClickUp Folder API

Before you can call the Get Folder endpoint, make sure you have the following items ready:

  • A ClickUp workspace with access to the folder you want to read.
  • An API token generated from your ClickUp profile or app configuration.
  • The numeric folder_id you want to retrieve.
  • A tool to make HTTP requests, such as curl, Postman, or a server-side script.

Without these prerequisites, the ClickUp platform will not authorize the request or will be unable to find the specified folder.

Required Parameters for the ClickUp Get Folder Call

The Get Folder endpoint is straightforward and relies primarily on a single path parameter:

  • folder_id (required, path): The unique identifier of the folder you want to retrieve.

This ID is often obtained from other endpoints (such as listing folders on a space) or from the user interface URL when navigating to a specific folder.

ClickUp Folder Path Parameter Details

Within the path, replace {folder_id} with the actual numeric ID. For example:

GET https://api.clickup.com/api/v2/folder/123456

There are no query parameters required for the basic retrieval, which keeps the request easy to construct and maintain in your integration.

Setting Up Authentication for ClickUp API Requests

The ClickUp API uses a personal token or app token passed in the request headers.

Add the following header to your HTTP call:

Authorization: YOUR_CLICKUP_API_TOKEN

In most tools, you can set this under an Authorization or Headers section. Keep the token secret and do not embed it in public client-side code.

Example Headers for a ClickUp Folder Request

A typical request header set might look like this:

Authorization: <your-token>
Content-Type: application/json

The Content-Type header is good practice, even for GET requests, to standardize how data is interpreted.

Step-by-Step: Call the ClickUp Get Folder Endpoint

Use the following steps to retrieve a folder by ID.

1. Identify the ClickUp Folder ID

You must start by identifying the correct folder_id. You can:

  • Use a list or folders API endpoint to search for existing folders.
  • Copy the ID from the URL when viewing the folder inside the product interface.

2. Build the ClickUp Request URL

Once you have the ID, insert it into the endpoint path:

https://api.clickup.com/api/v2/folder/<folder_id>

Confirm that there are no extra slashes or trailing query strings unless required for your tooling.

3. Add Authentication and Send the Request

Prepare your call with the necessary headers and send the request:

GET /api/v2/folder/123456 HTTP/1.1
Host: api.clickup.com
Authorization: <your-token>
Content-Type: application/json

If authentication is valid and the folder exists, the API will return a JSON object describing the folder.

Understanding the ClickUp Folder Response

When the request is successful, the response body contains structured JSON describing the folder. It typically includes fields such as:

  • id: The folder ID as a string.
  • name: The human-readable folder name.
  • orderindex: Position or sort order within its parent.
  • override_statuses: Indicates whether the folder overrides space-level statuses.
  • hidden: Whether the folder is hidden.
  • space: An object with the parent space information.
  • lists: An array of lists within the folder, each with its own metadata.

Depending on configuration, more fields may appear, such as status collections or permission details.

Typical HTTP Status Codes from the ClickUp API

The response status code helps you quickly identify success or failure:

  • 200 OK: The folder was found and returned successfully.
  • 401 Unauthorized: Missing, invalid, or expired token.
  • 403 Forbidden: Token is valid but does not have access to this folder.
  • 404 Not Found: The requested folder_id does not exist or is not accessible in the current workspace.

Use both the status code and any error message in the response body to guide debugging.

Using ClickUp Folder Data in Your Integration

Once you have the folder JSON payload, you can incorporate its data into your system. Common use cases include:

  • Displaying folder names and statuses in custom dashboards.
  • Using the contained list IDs to sync or mirror tasks.
  • Building automations that trigger on folder-level structure.

Because the ClickUp platform organizes work by spaces, folders, lists, and tasks, folder information is a central part of any robust integration strategy.

Best Practices for Working with the ClickUp Folder API

  • Cache folder metadata where appropriate to reduce API calls.
  • Handle 404 and permission errors gracefully in user-facing apps.
  • Log response bodies when debugging integration behavior.
  • Protect your token and rotate it according to security policies.

Where to Learn More About the ClickUp API

You can explore additional objects and endpoints, such as spaces, lists, and tasks, in the official documentation. This will help you design more complete workflows around your folder retrieval logic.

By combining this endpoint with related resources, you can create powerful integrations that fully leverage the information stored in each ClickUp folder.

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

“`