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


Start with Summary reports	Test your Workspace ID and API key using the Summary report first. It's the fastest to validate and confirms your credentials are correct before moving to heavier Detailed reports.
Use macros for rolling date ranges	Instead of manually updating dates, use macros like {{lastweekstart}}, {{thismonthstart}}, or {{30daysago}} to automatically pull the latest data on each refresh. This eliminates manual edits.
Separate reports by purpose	Create different data flows for billing (Detailed), dashboards (Summary), and capacity planning (Weekly) rather than cramming everything into one flow. Each report type is optimized for different use cases.

## Data refresh and scheduling


Schedule during low-usage hours	If your team logs time throughout the day, schedule imports during off-hours (early morning or evening) to avoid pulling incomplete daily data and reduce API conflicts.
Match refresh frequency to your workflow	Daily refreshes work well for Summary reports used in dashboards. Weekly refreshes are better for billing-focused Detailed reports to batch-process completed time entries.

## Performance optimization


Use narrower date ranges for large workspaces	If you have hundreds of users or years of data, split imports into monthly windows rather than pulling a full year at once. This avoids timeouts and keeps refreshes fast.
Archive old data separately	Keep a historical export in one sheet and a rolling current-month import in another. This prevents bloat and makes dashboards respond faster.

## Common pitfalls {% columns %} {% column %} **Do** * Regenerate your API key if you get 401 errors * Set end dates one day after your intended range (e.g., `2024-12-01` to capture through November 30) * Test with a manual run before scheduling * Use a Summary report to validate your credentials first {% endcolumn %} {% column %} **Don't** * Assume the Workspace ID from the URL is the same across workspaces—always copy it fresh * Leave date range blank if you need predictable data—always specify both start and end dates * Schedule multiple large imports simultaneously—stagger them to avoid rate limits * Try to filter by user or project in Coupler.io settings—use spreadsheet formulas instead {% 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/time-tracking/clockify/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.