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

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

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