# 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 %}