How to Use ClickUp Folderless Lists via API

This guide explains how to use the ClickUp API to retrieve folderless lists from a space, covering the endpoint, headers, parameters, and common usage patterns.

You will learn how to authenticate, construct the request URL, add optional filters, and interpret the response so you can reliably work with lists that are not inside folders.

Understanding the ClickUp Folderless Lists Endpoint

The ClickUp REST API provides a dedicated endpoint for getting lists that live directly in a space rather than inside folders.

This endpoint is useful when you organize work with a mix of lists in folders and lists at the space root and need to treat them differently in your integrations or automations.

Endpoint Overview

• HTTP method: GET
• Path: /api/v2/space/{space_id}/list
• Purpose: Return all folderless lists belonging to a specific space.

Only lists that are not nested inside folders are returned. Lists in folders must be fetched from the folder-based list endpoint, which is different from this one.

Prerequisites for Using the ClickUp API

Before calling this ClickUp endpoint, confirm you have the following in place:

• A valid ClickUp workspace and space where your folderless lists are stored.
• An API token with permission to read lists in the target space.
• The numeric space_id for the space whose lists you want to retrieve.
• A tool to make HTTP requests, such as curl, Postman, or a custom script.

You should also be comfortable handling JSON responses and basic HTTP status codes when working with the ClickUp platform programmatically.

Required Authentication and Headers in ClickUp

Requests to this ClickUp endpoint must include the proper authentication header so the API can identify your user or integration.

Authorization Header

• Header name: Authorization
• Header value: your personal or app API token.

Example header:

Authorization: <your_clickup_api_token>

Always keep your ClickUp token secret. Store it in secure configuration or environment variables and never commit it to public repositories.

Content Type

Because this is a GET request that does not send a body, a Content-Type header is generally not necessary. The response is returned as JSON by default, which is typical for the ClickUp REST API.

Path Parameter: space_id in ClickUp

The space_id path parameter tells ClickUp which space to query for folderless lists.

• Parameter: space_id
• Type: string or numeric ID
• Location: part of the URL path

You can obtain the space ID from other parts of the ClickUp API or from the web app URL when a space is selected, depending on your workflow.

Sample Request URL

Example of a full request URL with a fictional ID:

https://api.clickup.com/api/v2/space/123456/list

Replace 123456 with the actual space ID from your ClickUp workspace.

Optional Query Parameters in ClickUp Folderless Lists

The folderless lists endpoint supports query parameters to filter or modify the returned data. The exact options are documented on the official reference page.

Typical query parameters on ClickUp list endpoints include options for pagination and filtering. For example, you may see parameters similar to:

• archived to control whether archived lists are included.
• Pagination controls like page or limit (varies by endpoint version).

Check the official API reference at ClickUp folderless lists documentation for the latest, authoritative list of options.

Step-by-Step: Getting Folderless Lists from ClickUp

Follow these steps to make your first successful request to the folderless lists endpoint in ClickUp.

1. Locate Your Space ID

1. Open the ClickUp app.
2. Navigate to the target space containing your folderless lists.
3. Retrieve the space_id from the API or from the URL if you already use other API calls.

2. Prepare Your ClickUp API Token

1. Log in to your ClickUp account.
2. Generate or copy your personal API token from the user settings or developer settings area.
3. Store the token securely so you can reference it in your requests.

3. Build the Request URL

1. Start with the base URL: https://api.clickup.com/api/v2.
2. Append the path: /space/{space_id}/list.
3. Insert your real space_id into the path.
4. Add any query parameters you need for filtering or pagination.

The final URL might look like:

https://api.clickup.com/api/v2/space/123456/list?archived=false

4. Add Headers and Send the Request

Example curl request:

curl -X GET \
  'https://api.clickup.com/api/v2/space/123456/list' \
  -H 'Authorization: <your_clickup_api_token>'

Send the request using your preferred HTTP client. The ClickUp API will respond with a JSON payload describing the folderless lists in the specified space.

Interpreting the ClickUp API Response

The response from this ClickUp endpoint is in JSON format and typically includes:

• An array of list objects.
• Each list’s ID, name, status, and other metadata.
• Any additional fields exposed by the API version you are using.

You can use these list IDs in subsequent requests, for example to read tasks within a list or to update list settings, depending on your integration requirements.

Handling Errors from the ClickUp Endpoint

When working with the folderless lists endpoint in ClickUp, watch for common HTTP status codes:

• 200 – Request succeeded and the lists are returned.
• 401 – Authentication failed, often due to a missing or invalid token.
• 404 – The space ID is invalid or you do not have access.
• 429 – Rate limit reached; you may need to slow down your requests.

Always check the response body for error messages or additional details and adjust your request accordingly.

Best Practices for Working with ClickUp Folderless Lists

To build robust integrations with ClickUp around folderless lists, apply these practical tips:

• Cache list IDs where appropriate to reduce repeated calls.
• Use query parameters to limit the data you request and stay within rate limits.
• Implement retries with backoff when you encounter transient errors or rate limiting.
• Monitor for changes in the official API documentation, as parameters or response structures may evolve.

If you are designing a larger workflow automation or reporting system, combining folderless list data with other ClickUp endpoints can give you a more complete view of work across your spaces.

Where to Learn More About ClickUp API Usage

For complete technical details on this specific endpoint, always refer to the official ClickUp folderless lists API documentation, which includes the latest parameters, request samples, and response schemas.

To explore broader strategy, implementation patterns, and automation design beyond a single ClickUp endpoint, you can also review external resources such as Consultevo, which covers modern workflow and integration practices.

By following this guide and the official reference, you can confidently integrate folderless lists from ClickUp into your applications, dashboards, and automation workflows.

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

“`