> 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.md).

# Buildkite

Connect Buildkite CI/CD pipelines to Coupler.io and pull build performance, agent clusters, and test analytics into Google Sheets or BigQuery.

Buildkite is a CI/CD platform that lets engineering teams run fast, scalable pipelines on their own infrastructure. It gives you full visibility into build executions, pipeline health, agent clusters, and test analytics — all in one place.

Connecting Buildkite to Coupler.io lets you pull that data into your reporting tools so you can track build performance, monitor pipeline reliability, and share insights with your team without manual exports.

## Why connect Buildkite to Coupler.io?

* **Centralize CI/CD metrics** — combine build data with project management or incident data in one dashboard
* **Track pipeline health over time** — analyze build success rates, durations, and failure trends across pipelines
* **Share data without API access** — export Buildkite data to Google Sheets, Excel, or BI tools for non-technical stakeholders
* **AI-powered analysis** — send build data to ChatGPT, Claude, or Gemini to surface patterns and anomalies

## Prerequisites

* A Buildkite account with at least one organization
* A Buildkite API access token with read permissions for the entities you want to export (generate one in **Personal Settings → API Access Tokens**)

## Quick start

{% hint style="success" %}
Start with the **Builds** or **Organizations pipelines builds** entity — these give you the richest data for pipeline health reporting right away.
{% endhint %}

## How to connect

{% stepper %}
{% step %}
**Create a new data flow in Coupler.io.** Go to your Coupler.io dashboard and click **Add data flow**. Search for and select **Buildkite** as your source.
{% endstep %}

{% step %}
**Enter your Buildkite API token.** In the source settings, paste your Buildkite API access token. You can generate one in Buildkite under **Personal Settings → API Access Tokens**. Make sure the token has the appropriate read scopes for the entities you plan to export.
{% endstep %}

{% step %}
**Select an entity.** Choose which Buildkite entity you want to pull — for example, **Builds**, **Organizations pipelines**, or **Analytics organizations suites**. If you want data from multiple entities, you can add more sources to the same data flow.
{% endstep %}

{% step %}
**Set a start date.** Use the date picker to specify the earliest date for data extraction. Buildkite will return data from that date onward.
{% endstep %}

{% step %}
**Choose a destination.** Select where you want your data to land — Google Sheets, Excel, BigQuery, Looker Studio, or an AI destination like ChatGPT, Claude, or Gemini.
{% endstep %}

{% step %}
**Run the data flow.** Click **Run** to execute your first manual sync. Once it completes successfully, your Buildkite data will appear in your chosen destination.
{% endstep %}
{% endstepper %}

## Buildkite data overview

Buildkite exposes data across your CI/CD operations — from high-level organization and pipeline configuration to granular build executions and test analytics. Here's what you can access through Coupler.io.

## Available entities

| Entity                         | What it contains                                                    |
| ------------------------------ | ------------------------------------------------------------------- |
| Organizations                  | Org name, slug, billing plan, agent count, created date             |
| Analytics organizations suites | Test suite names, IDs, org association, analytics metadata          |
| Organizations pipelines        | Pipeline name, slug, URL, build settings, default branch, badge URL |
| Organizations builds           | Build number, state, commit, branch, message, creator, timing       |
| Organizations pipelines builds | Same as builds but scoped per pipeline                              |
| Builds                         | Build state, number, branch, commit SHA, timing, pipeline reference |
| Organizations clusters         | Cluster name, ID, description, associated queues                    |
| Organizations clusters queues  | Queue key, cluster ID, dispatch paused status                       |
| Organizations clusters tokens  | Token description, cluster ID, created/updated timestamps           |
| Organizations emojis           | Emoji name, URL, created date                                       |
| Access tokens                  | Token UUID, description, scopes, created date                       |
| Users                          | Name, email, avatar URL, created date                               |

## Builds data

#### Build status fields

| Field   | Description                                                       |
| ------- | ----------------------------------------------------------------- |
| State   | Build state: `passed`, `failed`, `running`, `blocked`, `canceled` |
| Number  | Sequential build number within the pipeline                       |
| Branch  | Git branch the build ran on                                       |
| Commit  | Full commit SHA                                                   |
| Message | Commit message or build reason                                    |
| Source  | What triggered the build (e.g., webhook, API, schedule)           |

#### Build timing fields

| Field        | Description                    |
| ------------ | ------------------------------ |
| Created at   | When the build was created     |
| Started at   | When the build started running |
| Finished at  | When the build completed       |
| Scheduled at | When the build was scheduled   |

## Pipeline data

#### Pipeline configuration fields

| Field                  | Description                             |
| ---------------------- | --------------------------------------- |
| Name                   | Pipeline display name                   |
| Slug                   | URL-friendly pipeline identifier        |
| Repository             | Repository URL the pipeline builds from |
| Default branch         | The default branch for builds           |
| Running builds count   | Number of currently running builds      |
| Scheduled builds count | Number of queued/scheduled builds       |
| Created at             | Pipeline creation date                  |

## Analytics data

#### Test suite fields

| Field             | Description                            |
| ----------------- | -------------------------------------- |
| Suite name        | Name of the test suite                 |
| Suite ID (slug)   | Unique identifier for the suite        |
| Organization slug | The org the suite belongs to           |
| Default branch    | Default branch tracked for test trends |

## Common metric combinations

* **Build success rate** — combine `state` and `number` from Builds to calculate pass/fail ratios over time
* **Pipeline throughput** — use `created_at` and `finished_at` from Organizations pipelines builds to measure build frequency and duration per pipeline
* **Cluster queue depth** — join Organizations clusters with Organizations clusters queues to see how jobs are distributed across agents
* **User activity** — combine Users with Organizations builds to attribute builds to team members

## Use cases by role

{% tabs %}
{% tab title="Engineering managers" %}

* Track build success rates across teams and pipelines to identify reliability issues early
* Compare pipeline performance over sprints to catch regressions before they become problems
* Use the Builds entity with Aggregate transformation to calculate average build duration per pipeline
  {% endtab %}

{% tab title="DevOps / Platform teams" %}

* Monitor agent cluster queue depths using Organizations clusters queues to right-size your infrastructure
* Export Organizations pipelines builds to BigQuery for long-term trend analysis and capacity planning
* Join Builds with Analytics organizations suites to correlate test failures with build failures
  {% endtab %}

{% tab title="Engineering leads" %}

* Use Organizations builds data in Looker Studio to build a live CI health dashboard shared with leadership
* Send build failure summaries to ChatGPT or Claude for automated root cause pattern analysis
* Append builds from multiple pipelines using the Append transformation to get a unified view across repos
  {% endtab %}
  {% endtabs %}

## Platform-specific notes

* The `start_date` parameter applies to time-series entities like Builds — set it carefully to avoid pulling more data than you need
* Some entities (Organizations emojis, Access tokens) are configuration data and don't change often — you won't need to refresh these frequently
* `organizations_pipelines_builds` is the most granular builds entity and is best for per-pipeline reporting; `builds` gives a flat cross-pipeline view
* Buildkite API responses are paginated — Coupler.io handles pagination automatically
* Test analytics data via Analytics organizations suites requires Buildkite Test Analytics to be enabled and configured in your org

## Buildkite common issues

### Connection issues

<details>

<summary>API token is rejected or authentication fails</summary>

Double-check that you've copied the full API token from Buildkite — no extra spaces or missing characters. Also confirm the token hasn't been revoked in **Personal Settings → API Access Tokens**. If you generated the token a while ago and it no longer works, create a new one and update it in your Coupler.io data flow settings.

</details>

<details>

<summary>Data flow connects but returns no data</summary>

This usually means the API token doesn't have the required read scopes for the entity you selected. In Buildkite, open the token settings and verify that it includes `read_builds`, `read_pipelines`, or the relevant scope for your entity. Regenerate with the correct scopes if needed.

</details>

### Missing data

<details>

<summary>Builds are missing from the export</summary>

Check your **start date** setting. If the start date is set too recently, older builds won't be included. Use the date picker to move the start date back further. Also verify that the builds you're looking for exist in the specific pipeline and organization you've selected.

</details>

<details>

<summary>Analytics suites entity returns empty results</summary>

Buildkite Test Analytics must be actively configured in your organization and have data ingested before this entity returns results. If you've only recently set up Test Analytics, there may not be enough data yet. Check in the Buildkite dashboard under **Analytics** to confirm suite data is present.

</details>

<details>

<summary>Only seeing data for some pipelines, not all</summary>

Your API token may only have access to specific pipelines or organizations. Buildkite token scopes can be restricted to particular resources. Confirm the token has org-level read access, or generate a new token with broader permissions.

</details>

### Permission errors

<details>

<summary>403 Forbidden error when pulling certain entities</summary>

This means your API token doesn't have permission to access that resource. Cluster tokens, access token details, and some org-level entities require elevated permissions. Review the required scopes for the entity in Buildkite's API documentation and update your token accordingly.

{% hint style="warning" %}
Organization-level entities like Organizations clusters tokens may require a token with admin-level scopes. Be careful when sharing data flows that include these entities.
{% endhint %}

</details>

### Data discrepancies

<details>

<summary>Build counts in Coupler.io don't match the Buildkite dashboard</summary>

The Buildkite dashboard may show builds that are still running or in a `scheduled` state at the time of your export. Coupler.io captures a point-in-time snapshot — builds that started after your data flow ran won't appear until the next run. Also check that your start date captures the same time range you're comparing against in the dashboard.

</details>

<details>

<summary>Build duration looks incorrect</summary>

Build duration is derived from `started_at` and `finished_at` timestamps. If a build was blocked or waited in a queue before running, the wall-clock time will differ from actual execution time. Use `started_at` rather than `created_at` as the start point for duration calculations.

</details>

### Rate limits

<details>

<summary>Data flow fails with a rate limit error</summary>

Buildkite enforces API rate limits per token. If you're running multiple data flows using the same API token and hitting limits, consider spreading out your scheduled runs. Alternatively, use a token associated with a service account rather than a personal user account to get a higher rate limit allowance.

</details>

## Buildkite FAQ

<details>

<summary>What's the difference between Builds, Organizations builds, and Organizations pipelines builds?</summary>

All three entities return build execution data, but at different scopes:

* **Builds** — a flat list of all builds across all pipelines in your account
* **Organizations builds** — builds scoped to a specific organization
* **Organizations pipelines builds** — builds scoped to a specific pipeline within an organization

For per-pipeline dashboards, use Organizations pipelines builds. For org-wide reporting, use Organizations builds. Builds is useful when you want a single dataset spanning everything.

</details>

<details>

<summary>Do I need a separate API token for each organization?</summary>

Not necessarily. A single Buildkite API token can have access to multiple organizations if your user account belongs to them. However, if you want to separate access by org or restrict permissions, you can create separate tokens and set up separate data flows — then use the Append transformation to combine the results.

</details>

<details>

<summary>Can I pull historical build data from the beginning of my account?</summary>

Yes — just set the start date to a far-back date using the date picker. Keep in mind that pulling years of build history from a large organization can be slow and may consume significant API quota. It's better to do a one-time historical pull and then schedule incremental refreshes going forward.

</details>

<details>

<summary>Why does the Analytics organizations suites entity return no rows?</summary>

This entity requires Buildkite Test Analytics to be enabled and have data ingested in your organization. If you haven't set up Test Analytics yet, or if no test runs have been reported, the entity will return empty. Check your Buildkite dashboard under **Analytics** to confirm suites exist before pulling this entity.

</details>

<details>

<summary>Can I combine Buildkite build data with data from other tools?</summary>

Yes. Coupler.io lets you add multiple sources to a single data flow. For example, you can join Buildkite Builds with Jira issues or GitHub pull request data to correlate deployment frequency with ticket throughput. Use the Join or Append transformation depending on whether you're enriching records or stacking them.

</details>

<details>

<summary>Can I send Buildkite data to an AI tool for analysis?</summary>

Yes. Coupler.io supports AI destinations including ChatGPT, Claude, Gemini, Cursor, Perplexity, and OpenClaw. You can send failed build summaries, pipeline metrics, or test analytics data directly to these tools for automated pattern detection or natural language reporting.

</details>

<details>

<summary>How often should I refresh my Buildkite data?</summary>

It depends on the entity. For build data used in live dashboards, hourly or every few hours is reasonable. For configuration entities like clusters, pipelines, and emojis, daily is usually more than enough. See the scheduling guidance for more detail.

{% hint style="info" %}
For scheduling tips and start date guidance, see [Best Practices](https://docs.coupler.io/sources/category/project-management/buildkite/best-practices.md). For issues with missing or incomplete data, see [Common Issues](#buildkite-common-issues).
{% endhint %}

</details>

<details>

<summary>Which entities are best for a CI/CD health dashboard?</summary>

For a solid CI/CD health dashboard, start with:

* **Organizations pipelines builds** — build success/failure rates and durations per pipeline
* **Organizations pipelines** — pipeline metadata like default branch and repository
* **Analytics organizations suites** — test pass rates if you use Buildkite Test Analytics

Join pipelines with their builds to enrich the dataset, then send it to Looker Studio, Google Sheets, or BigQuery for visualization.

{% hint style="info" %}
For a full breakdown of available fields in each entity, see [Data Overview](#buildkite-data-overview).
{% endhint %}

</details>


---

# 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 by asking a question.

Perform an HTTP GET request on the following URL with the `ask` and `goal` query parameters:

```
GET https://docs.coupler.io/sources/category/project-management/buildkite.md?ask=<question>&goal=<user_goal>
```

`ask` is the immediate question: it should be specific, self-contained, and written in natural language.
`goal` is what the user is ultimately trying to achieve, the reason they need the answer. Sharing it helps GitBook give you a better, more relevant answer. A goal is most helpful when it describes the outcome the user wants rather than restating the question. For example, with `ask=how do I create an API token`, a goal like `automate deployments from our CI pipeline` lets GitBook tailor the answer to that use case.

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.
