> 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/best-practices.md). # Best Practices ## Recommended setup


Use one entity per data flow for large workspaces	If you have thousands of tasks or many time entries, running Tasks, Time Trackings, and Custom Fields in separate data flows prevents API timeouts and partial syncs.
Always enable "Include closed tasks" for historical reporting	Closed tasks are excluded by default. If you're building completion rate or sprint velocity reports, you need historical data — turn this on in Advanced settings.
Use Tasks + Time Trackings with a Join transformation	Join on task_id to combine task metadata (name, status, assignee) with actual time logged. This is the foundation of most ClickUp productivity and billing reports.
Store Tasks and Time Trackings in separate tables in BigQuery	These are structurally different datasets. Appending them into one table will create schema conflicts. Use separate destinations or separate sheets/tables for each entity.

## Data refresh and scheduling


Run a successful manual sync before scheduling	Coupler.io requires a completed manual run before you can activate a schedule. Use the first run to verify your data looks correct before automating.
Stagger schedules across data flows	If you have multiple ClickUp data flows (e.g., Tasks, Time Trackings, Goals), offset their schedule times by 10–15 minutes. This avoids simultaneous API calls that can trigger rate limit errors.

## Performance optimization


Use Aggregate transformation for summary reports	Instead of loading raw task data into a spreadsheet and summarizing manually, use Coupler.io's Aggregate transformation to pre-compute totals (e.g., tasks by status, hours by user) before they land in your destination.
Use Append for multi-workspace reporting	If your team uses multiple ClickUp workspaces, connect each with a separate API token and use the Append transformation to combine them into a single unified dataset.

## Common pitfalls {% hint style="danger" %} Don't use a shared or admin token if it belongs to a user with restricted access to certain spaces. The data export will silently exclude anything that token can't see — with no error message. {% endhint %} {% columns %} {% column %} **Do** * Use the personal API token of a user with full workspace access * Enable **Include closed tasks** for any historical or retrospective analysis * Split large entity sets across multiple data flows * Convert `duration` (milliseconds) to hours in your destination or transformation layer {% endcolumn %} {% column %} **Don't** * Run 8+ entities simultaneously in one data flow — it overloads the API * Expect the Lists entity to return tasks — add the Tasks entity separately * Assume deactivated users' time entries will appear in exports * Append Tasks and Time Trackings into the same table — their schemas are incompatible {% endcolumn %} {% endcolumns %} --- # 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 dynamically by asking a question. Perform an HTTP GET request on the current page URL with the `ask` query parameter, and the optional `goal` query parameter: ``` GET https://docs.coupler.io/sources/category/project-management/clickup-api/best-practices.md?ask=&goal= ``` `ask` is the immediate question: it should be specific, self-contained, and written in natural language. `goal` is optional and describes the broader end goal you are ultimately trying to accomplish on behalf of the user. GitBook uses it to tailor the answer towards what is most useful for that goal. 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.