> 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/buildkite/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>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 %}


---

# 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/buildkite/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.