# 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 a narrow date range</strong></td><td>Set your start date to the last 30–90 days for your first run. This validates the connection quickly before you pull your full history.</td></tr><tr><td><strong>Use separate entities for tasks and scheduling</strong></td><td>Add Todos and Schedule entries as separate sources in the same data flow, then use Join or Append to combine them. Mixing entity types in a single source makes filtering harder downstream.</td></tr><tr><td><strong>Join on project_id</strong></td><td>Most entities include a project_id field. Use Coupler.io's Join transformation to enrich Todos, Messages, and Schedule entries with project names from the Projects entity.</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>Match refresh frequency to your team's cadence</strong></td><td>Daily refreshes work well for task tracking. If you're monitoring active sprints or deadlines, consider more frequent syncs to keep schedule entries current.</td></tr><tr><td><strong>Stagger multi-entity data flows</strong></td><td>If you have multiple data flows pulling from Basecamp, schedule them a few minutes apart to avoid hitting API rate limits simultaneously.</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>Filter by status in your destination</strong></td><td>The Todos entity includes completed tasks. Filter by completed = false in Google Sheets or BigQuery rather than pulling only recent data — this gives you a full open task list without adjusting the start date constantly.</td></tr><tr><td><strong>Use AI destinations for unstructured data</strong></td><td>Messages contain free-text content that's hard to analyze in a spreadsheet. Pipe Messages data into ChatGPT, Claude, or Gemini to extract themes, sentiment, or action items automatically.</td></tr></tbody></table>

## Common pitfalls

{% hint style="danger" %}
Do not connect a Basecamp 2 or Basecamp Classic account — these are not supported and the connection will fail. There is no compatibility workaround.
{% endhint %}

{% columns %}
{% column %}
**Do**

* Use the Projects entity as your lookup table and join other entities to it on project\_id
* Flatten assignee arrays in your destination before building reports
* Test with a short start date range before expanding to your full history
  {% endcolumn %}

{% column %}
**Don't**

* Pull Schedules and Schedule entries as if they're the same data — they're separate entities with different fields
* Assume every row in Todos is an individual task — filter by record type to exclude list containers
* Use the same API token across multiple team members' data flows if those users have different project access levels
  {% endcolumn %}
  {% endcolumns %}