> 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/project-management/basecamp/best-practices.md).

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


---

# 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/project-management/basecamp/best-practices.md?ask=<question>&goal=<endgoal>
```

`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.