# Best Practices

## Recommended setup

<table data-card-size="large" data-view="cards"><thead><tr><th></th><th></th></tr></thead><tbody><tr><td><strong>Use organizations_pipelines_builds for per-pipeline reporting</strong></td><td>This entity scopes builds to a specific pipeline, making it easier to calculate pipeline-level metrics like success rate and mean build time without needing to filter a large flat Builds dataset.</td></tr><tr><td><strong>Add multiple entities to one data flow</strong></td><td>Rather than creating separate data flows for Builds and Organizations pipelines, add both as sources in a single data flow and use the Join transformation to enrich build records with pipeline metadata like default branch and repository URL.</td></tr><tr><td><strong>Append builds from multiple organizations</strong></td><td>If your Coupler.io account has tokens for multiple Buildkite organizations, use the Append transformation to combine their build data into a single unified dataset for cross-org reporting.</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>Set your start date to match your reporting window</strong></td><td>Pulling 90 days of builds for a daily dashboard wastes API quota. Set the start date to match your actual reporting window — for a rolling weekly report, 14 days is usually enough to cover the current and previous week.</td></tr><tr><td><strong>Refresh configuration entities less frequently</strong></td><td>Entities like Organizations emojis, Organizations clusters, and Access tokens rarely change. Schedule these less frequently than build data — daily or even weekly is sufficient.</td></tr><tr><td><strong>Schedule around your peak build times</strong></td><td>If your pipelines run heavily during business hours, schedule Coupler.io data flows to run shortly after your peak window closes. This way your reports reflect a complete picture of the day's build activity.</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 Aggregate to pre-calculate build metrics</strong></td><td>Rather than exporting every build row to a spreadsheet and calculating success rates there, use Coupler.io's Aggregate transformation to compute pass/fail counts and average durations before the data lands in your destination.</td></tr><tr><td><strong>Send build failure summaries to AI destinations</strong></td><td>Export failed builds to ChatGPT, Claude, or Gemini to automatically identify patterns in failure messages, branch names, or commit authors — useful for spotting recurring issues without manually scanning logs.</td></tr></tbody></table>

## Common pitfalls

{% hint style="danger" %}
Don't use a personal API token with broad scopes for shared data flows. If that token is revoked or rotated, all data flows depending on it will break simultaneously. Create a dedicated service account token for Coupler.io integrations.
{% endhint %}

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

* Use a dedicated Buildkite API token scoped to only the entities you need
* Set a specific start date to limit data volume and API usage
* Join Builds with Pipelines to add pipeline context to build records
* Run a manual data flow first before setting up a schedule
  {% endcolumn %}

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

* Pull the full Builds history without a start date filter on large orgs
* Reuse the same personal API token across multiple Coupler.io data flows
* Rely on Organizations emojis or Users entities for real-time data — these are slow-changing config entities
* Mix `created_at` and `started_at` timestamps when calculating build duration
  {% endcolumn %}
  {% endcolumns %}