Best Practices

Recommended setup

Use organizations_pipelines_builds for per-pipeline reporting

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.

Add multiple entities to one data flow

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.

Append builds from multiple organizations

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.

Data refresh and scheduling

Set your start date to match your reporting window

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.

Refresh configuration entities less frequently

Entities like Organizations emojis, Organizations clusters, and Access tokens rarely change. Schedule these less frequently than build data — daily or even weekly is sufficient.

Schedule around your peak build times

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.

Performance optimization

Use Aggregate to pre-calculate build metrics

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.

Send build failure summaries to AI destinations

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.

Common pitfalls

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.

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

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