# Best Practices

## Recommended setup

<table data-card-size="large" data-view="cards"><thead><tr><th></th><th></th></tr></thead><tbody><tr><td><strong>Start with Summary reports</strong></td><td>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.</td></tr><tr><td><strong>Use macros for rolling date ranges</strong></td><td>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.</td></tr><tr><td><strong>Separate reports by purpose</strong></td><td>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.</td></tr></tbody></table>

## Data refresh and scheduling

<table data-card-size="large" data-view="cards"><thead><tr><th></th><th></th></tr></thead><tbody><tr><td><strong>Schedule during low-usage hours</strong></td><td>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.</td></tr><tr><td><strong>Match refresh frequency to your workflow</strong></td><td>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.</td></tr></tbody></table>

## Performance optimization

<table data-card-size="large" data-view="cards"><thead><tr><th></th><th></th></tr></thead><tbody><tr><td><strong>Use narrower date ranges for large workspaces</strong></td><td>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.</td></tr><tr><td><strong>Archive old data separately</strong></td><td>Keep a historical export in one sheet and a rolling current-month import in another. This prevents bloat and makes dashboards respond faster.</td></tr></tbody></table>

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