> For the complete documentation index, see [llms.txt](https://docs.coupler.io/llms.txt). Markdown versions of documentation pages are available by appending `.md` to page URLs; this page is available as [Markdown](https://docs.coupler.io/sources/category/project-management/clickup-api.md).

# ClickUp

Export ClickUp tasks, time tracking, goals, and team data to Google Sheets, BigQuery, Power BI, or AI tools via Coupler.io.

ClickUp is a project management platform where teams track tasks, manage workflows, log time, and organize work across spaces, folders, and lists. Connecting ClickUp to Coupler.io lets you pull that data into spreadsheets, BI tools, or AI assistants — without manual exports.

**Why connect ClickUp to Coupler.io?**

* Export tasks, time tracking, goals, and team data to Google Sheets, BigQuery, Power BI, Looker Studio, Excel, or AI tools like ChatGPT, Claude, or Gemini
* Combine multiple ClickUp entities (e.g., Tasks + Time Trackings) using Join or Append transformations to build richer reports
* Keep your dashboards and reports up to date with scheduled syncs
* Access custom fields from lists and teams as structured columns in your destination

## Prerequisites

* A ClickUp account with access to the workspaces you want to export
* A ClickUp personal API token (found in your ClickUp profile settings)
* Coupler.io account (free plan available)

{% hint style="warning" %}
Coupler.io pulls data based on your personal API token. You'll only see spaces, tasks, and users that your ClickUp account has permission to access. Private spaces or tasks shared with other members won't appear unless your account has explicit access.
{% endhint %}

## Quick start

{% hint style="success" %}
Start with the **Tasks** entity — it's the most data-rich ClickUp entity and the most common starting point for project reporting.
{% endhint %}

{% stepper %}
{% step %}
**Get your ClickUp API token.** In ClickUp, click your avatar in the bottom-left corner, go to **Settings**, then scroll to **Apps**. Click **Generate** (or copy your existing token) under Personal API Token.
{% endstep %}

{% step %}
**Create a new data flow in Coupler.io.** Go to your Coupler.io dashboard and click **Add data flow**. Search for and select **ClickUp** as the source.
{% endstep %}

{% step %}
**Enter your API token.** Paste your ClickUp personal API token into the connection field and click **Connect**.
{% endstep %}

{% step %}
**Select an entity.** Choose the data you want to export — for example, Tasks, Time Trackings, or Team Goals. You can add more entities to the same data flow later.
{% endstep %}

{% step %}
**Choose a destination.** Select where you want your data to land — Google Sheets, BigQuery, Power BI, Excel, Looker Studio, or an AI destination like ChatGPT or Claude.
{% endstep %}

{% step %}
**Run your data flow.** Click **Run** to execute a manual sync. Once it completes successfully, your data will appear in the destination.
{% endstep %}
{% endstepper %}

## Available entities

| Entity             | What it contains                                         |
| ------------------ | -------------------------------------------------------- |
| Tasks              | Task details, statuses, assignees, due dates, priorities |
| Time Trackings     | Time entries logged against tasks                        |
| Time Tracking Tags | Tags used in time tracking entries                       |
| Users              | Workspace members and their details                      |
| Teams              | Workspace/team structure                                 |
| Spaces             | Top-level spaces in a workspace                          |
| Folders            | Folders within spaces                                    |
| Lists              | Lists within folders or spaces                           |
| List Custom Fields | Custom field definitions for lists                       |
| Team Custom Fields | Custom field definitions for teams                       |
| Space Tags         | Tags defined at the space level                          |
| Team Goals         | Goals tracked at the team level                          |
| List Comments      | Comments on lists                                        |

## ClickUp data overview

ClickUp exposes a wide range of project and team data through Coupler.io. Depending on which entities you select, you can access everything from individual task details and time logs to workspace structure, custom fields, and team goals.

## Entities summary

| Entity             | Best used for                                                     |
| ------------------ | ----------------------------------------------------------------- |
| Tasks              | Core project reporting — status, assignees, deadlines, priorities |
| Time Trackings     | Billable hours, productivity analysis, time-per-task              |
| Time Tracking Tags | Categorizing time entries by type or project                      |
| Users              | Team member directory, role mapping                               |
| Teams              | Workspace-level groupings                                         |
| Spaces             | Top-level organizational structure                                |
| Folders            | Mid-level structure within spaces                                 |
| Lists              | Task containers — granular organization                           |
| List Custom Fields | Custom metadata defined per list                                  |
| Team Custom Fields | Custom metadata defined at the team level                         |
| Space Tags         | Tag taxonomy at the space level                                   |
| Team Goals         | OKRs and targets tracked in ClickUp                               |
| List Comments      | Comments associated with lists                                    |

## Tasks

#### Key fields

| Field                     | Description                                           |
| ------------------------- | ----------------------------------------------------- |
| id                        | Unique task identifier                                |
| name                      | Task title                                            |
| status                    | Current task status (e.g., Open, In Progress, Closed) |
| priority                  | Priority level (Urgent, High, Normal, Low)            |
| assignees                 | Users assigned to the task                            |
| due\_date                 | Task due date                                         |
| date\_created             | When the task was created                             |
| date\_updated             | Last modified timestamp                               |
| list\_id / list\_name     | List the task belongs to                              |
| space\_id / space\_name   | Space the task belongs to                             |
| folder\_id / folder\_name | Folder containing the task                            |
| tags                      | Tags applied to the task                              |
| time\_estimate            | Estimated time in milliseconds                        |
| custom\_fields            | Custom field values (exported as separate columns)    |

{% hint style="info" %}
Closed tasks are excluded by default. Enable **Include closed tasks** in the data flow settings if you need historical or completed task data.
{% endhint %}

## Time Trackings

#### Key fields

| Field    | Description                    |
| -------- | ------------------------------ |
| id       | Time entry identifier          |
| task\_id | Associated task                |
| user\_id | User who logged the time       |
| duration | Time logged (in milliseconds)  |
| start    | Start timestamp of the entry   |
| end      | End timestamp of the entry     |
| tags     | Tags applied to the time entry |
| billable | Whether the entry is billable  |

{% hint style="warning" %}
Deactivated users do not appear in time tracking exports, even if they logged time in the past. This is a ClickUp API limitation — historical entries from removed users may not be retrievable.
{% endhint %}

## Users

#### Key fields

| Field        | Description           |
| ------------ | --------------------- |
| id           | User identifier       |
| username     | ClickUp username      |
| email        | User email address    |
| role         | Role in the workspace |
| date\_joined | When the user joined  |

## Team Goals

#### Key fields

| Field              | Description                   |
| ------------------ | ----------------------------- |
| id                 | Goal identifier               |
| name               | Goal title                    |
| due\_date          | Target completion date        |
| percent\_completed | Progress percentage           |
| owner\_id          | User responsible for the goal |
| color              | Goal color label              |

## Common metric combinations

* **Tasks + Time Trackings** — Join on `task_id` to see how long each task took vs. its estimate
* **Tasks + Users** — Join on assignee ID to build workload reports per person
* **Time Trackings + Time Tracking Tags** — Join on tag ID to break down hours by category or project type
* **Multiple spaces/teams** — Use Append to combine task data from different workspaces into a single dataset

## Use cases by role

{% tabs %}
{% tab title="Project managers" %}

* Track task completion rates by assignee, list, or space
* Monitor overdue tasks by filtering on `due_date` vs. `date_updated`
* Report on goal progress using Team Goals data
* Compare estimated vs. actual time using Tasks + Time Trackings joined on `task_id`
  {% endtab %}

{% tab title="Finance & operations" %}

* Calculate billable hours per client or project using the Time Trackings `billable` field
* Build invoicing reports by joining Time Trackings with Users and tasks
* Aggregate logged hours by team member for payroll or capacity planning
  {% endtab %}

{% tab title="Team leads" %}

* Analyze workload distribution across team members
* Review custom field data (e.g., effort scores, sprint tags) exported from List Custom Fields
* Track sprint velocity by aggregating completed tasks per time period
  {% endtab %}
  {% endtabs %}

## Platform-specific notes

* The Lists entity returns list **metadata** (name, ID, status, task count) — not the tasks inside the list. Use the Tasks entity to get task-level data.
* Custom fields are exported as separate columns — you'll see them in your destination alongside standard task fields.
* ClickUp's API returns `duration` in milliseconds — divide by 3,600,000 to convert to hours in your destination.
* Data is scoped to your personal API token. Private spaces, private lists, and tasks you don't have access to won't be included.
* There is no native pagination limit advertised, but very large workspaces with thousands of tasks may experience slower syncs or partial data. Consider filtering by space or list where possible.

## ClickUp common issues

### Connection issues

<details>

<summary>API token not accepted or connection fails</summary>

Make sure you're using your **personal API token**, not an OAuth token or a team token. Find it in ClickUp under your avatar → **Settings** → **Apps** → Personal API Token. Copy the full token without any extra spaces.

If the connection still fails, try regenerating the token in ClickUp and entering the new one in Coupler.io.

</details>

<details>

<summary>Data flow runs but returns no data</summary>

This usually means your API token doesn't have access to the spaces or tasks you're trying to export. ClickUp respects workspace permissions — if you're not a member of a space or it's set to private, those items won't appear.

Check that the ClickUp account associated with your token has the correct access level. If a workspace owner set up the token but the data lives in a space shared only with other members, you'll need a token from a user with access to that space.

</details>

### Missing data

<details>

<summary>Closed or completed tasks are missing</summary>

By default, closed tasks are excluded from the export. Go to the **Advanced settings** step in your data flow and enable **Include closed tasks**.

</details>

<details>

<summary>Lists entity shows only metadata, not tasks</summary>

This is expected behavior. The **Lists** entity returns list-level metadata (name, ID, status) — not the individual tasks inside. To get task data, add the **Tasks** entity to your data flow.

</details>

<details>

<summary>Deactivated users don't appear in time tracking data</summary>

ClickUp's API does not return time entries for deactivated users, even for dates when they were active. This is a ClickUp API limitation and cannot be worked around through Coupler.io settings.

</details>

<details>

<summary>Custom fields are missing from the export</summary>

Custom fields are available through the **List Custom Fields** and **Team Custom Fields** entities. Add one of these entities to your data flow. For task-level custom field values, they should also appear as separate columns in the Tasks export — if they're missing, try re-running the data flow after adding the relevant custom fields entity.

</details>

### Data discrepancies

<details>

<summary>Fewer rows than expected — data appears truncated</summary>

Enabling too many entities in a single data flow can cause API calls to fail or time out, resulting in partial data. If you're seeing fewer rows than expected, try splitting your entities across separate data flows rather than running them all at once.

Very large workspaces (tens of thousands of tasks) may also hit processing limits. Adding filters or splitting by space can help.

</details>

<details>

<summary>Time tracking totals don't match ClickUp's built-in reports</summary>

ClickUp's API does not return time entries for deactivated users (see above). If your ClickUp reports include historical time from users who have since been deactivated, the totals will differ. Also check that you're converting milliseconds to hours correctly — divide the `duration` field by 3,600,000.

</details>

### Rate limits

<details>

<summary>Sync fails with timeout or rate limit errors</summary>

ClickUp's API has rate limits that apply per token. Running many entities simultaneously (Tasks, Time Trackings, Users, Custom Fields, etc.) can trigger rate limit errors or timeouts.

{% hint style="warning" %}
If you're running more than 4–5 entities in one data flow, consider splitting them into separate data flows and staggering their schedules to avoid hitting API limits.
{% endhint %}

</details>

## ClickUp FAQ

<details>

<summary>Where do I find my ClickUp API token?</summary>

In ClickUp, click your **avatar** in the bottom-left corner, go to **Settings**, then scroll down to **Apps**. Your personal API token is listed there — click **Generate** if you haven't created one yet, or copy the existing token.

</details>

<details>

<summary>Why am I only seeing list names, not the tasks inside them?</summary>

The **Lists** entity in Coupler.io returns list-level metadata — the list name, ID, and settings — not the tasks inside. To get task data, add the **Tasks** entity to your data flow.

</details>

<details>

<summary>Can I export custom fields from ClickUp?</summary>

Yes. Add the **List Custom Fields** or **Team Custom Fields** entity to your data flow. Custom field values also appear as separate columns in the Tasks export. If you recently added new custom fields in ClickUp, re-run the data flow to pick them up.

</details>

<details>

<summary>Why doesn't my data flow return all my tasks?</summary>

Two common reasons: first, closed tasks are excluded by default — enable **Include closed tasks** in Advanced settings. Second, if you're running many entities at once, some API calls may fail and return partial data. Try splitting entities across separate data flows.

</details>

<details>

<summary>Why are deactivated team members missing from time tracking exports?</summary>

ClickUp's API does not return time tracking entries for deactivated users. This applies even to historical entries logged before the user was deactivated. Unfortunately, this is a ClickUp API limitation that cannot be resolved through Coupler.io settings.

</details>

<details>

<summary>Can I combine ClickUp data from multiple workspaces?</summary>

Yes. Create a separate data flow for each workspace (using the API token of a user in that workspace), then use the **Append** transformation in Coupler.io to combine them into a single dataset in your destination.

</details>

<details>

<summary>Should tasks and time trackings go into the same table in BigQuery?</summary>

No — they have different schemas and should be stored in separate tables. Use a Join transformation in Coupler.io if you want to combine them, or reference them with separate queries/views in BigQuery. Appending them into the same table will cause schema conflicts.

</details>

<details>

<summary>Can I send ClickUp data to AI tools like ChatGPT or Claude?</summary>

Yes. Coupler.io supports AI destinations including ChatGPT, Claude, Gemini, Perplexity, Cursor, and OpenClaw. This lets you query your ClickUp task or time tracking data conversationally — useful for generating status summaries or identifying blockers.

</details>

<details>

<summary>Why does my data flow run successfully but show no data?</summary>

This usually means the API token you used doesn't have access to the spaces or tasks you're trying to export. ClickUp respects workspace permissions — private spaces and tasks you're not a member of won't appear. Make sure the token belongs to a user with the appropriate access level.

</details>

{% hint style="info" %}
For a full list of available fields and metric combinations, see the [Data Overview](#clickup-data-overview) article. For connection errors and partial data issues, check [Common Issues](#clickup-common-issues).
{% endhint %}


---

# Agent Instructions
This documentation is published with GitBook. GitBook is the documentation platform designed so that both humans and AI agents can read, navigate, and reason over technical content effectively. Learn more at gitbook.com.

## Querying This Documentation
If you need additional information that is not directly available in this page, you can query the documentation by asking a question.

Perform an HTTP GET request on the following URL with the `ask` and `goal` query parameters:

```
GET https://docs.coupler.io/sources/category/project-management/clickup-api.md?ask=<question>&goal=<user_goal>
```

`ask` is the immediate question: it should be specific, self-contained, and written in natural language.
`goal` is what the user is ultimately trying to achieve, the reason they need the answer. Sharing it helps GitBook give you a better, more relevant answer. A goal is most helpful when it describes the outcome the user wants rather than restating the question. For example, with `ask=how do I create an API token`, a goal like `automate deployments from our CI pipeline` lets GitBook tailor the answer to that use case.

The response will contain a direct answer to the question and relevant excerpts and sources from the documentation.

Use this mechanism when the answer is not explicitly present in the current page, you need clarification or additional context, or you want to retrieve related documentation sections.
