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

# Circleci

Pull CircleCI pipeline, workflow, and job data into Google Sheets, BigQuery, or BI tools via Coupler.io for CI/CD health tracking.

CircleCI is a continuous integration and delivery platform that automates your build, test, and deployment pipelines. It helps engineering teams ship code faster by running automated workflows whenever changes are pushed to a repository.

Connecting CircleCI to Coupler.io lets you pull pipeline, workflow, and job data into your destination of choice — whether that's a spreadsheet, a BI tool, or an AI assistant.

## Why connect CircleCI to Coupler.io?

* **Track CI/CD health over time** — export pipeline and job execution data to monitor build success rates, failure trends, and deployment frequency
* **Analyze performance metrics** — use Insights data to identify slow workflows, flaky jobs, and branches causing the most failures
* **Combine with other sources** — join CircleCI data with GitHub, Jira, or project management tools to get a full picture of your engineering delivery
* **Send data to AI tools** — pipe metrics into ChatGPT, Claude, Gemini, or other AI destinations to generate automated reports or spot anomalies

## Prerequisites

* A CircleCI account (Free, Performance, or Scale plan)
* A CircleCI **personal API token** — generate one at [User Settings → Personal API Tokens](https://app.circleci.com/settings/user/tokens)
* Your organization slug and project IDs (available in CircleCI project settings URLs)

## Quick start

{% hint style="success" %}
Start with the **Pipelines** or **Insights metrics** entity — these give you the broadest view of CI/CD activity right away.
{% endhint %}

## How to connect

{% stepper %}
{% step %}
**Create a new data flow.** In Coupler.io, click **Add data flow** and search for **CircleCI** as your source.
{% endstep %}

{% step %}
**Authenticate with your API key.** Paste your CircleCI personal API token into the API key field. You can generate a token at CircleCI → User Settings → Personal API Tokens.
{% endstep %}

{% step %}
**Select an entity.** Choose what data you want to pull — for example, Pipelines, Workflows, Jobs, or Insights metrics. See the table below for a full list of available entities.
{% endstep %}

{% step %}
**Set a start date.** Use the date picker to define how far back you want data to go. This controls the earliest records included in your export.
{% endstep %}

{% step %}
**Choose a destination.** Select where your data should 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 a manual sync and verify your data loads correctly.
{% endstep %}
{% endstepper %}

## CircleCI data overview

CircleCI exposes data across your entire CI/CD pipeline — from high-level project and pipeline records down to individual job runs and branch-level performance insights. Here's what you can access through Coupler.io.

## Available entities

| Entity              | What it contains                                          |
| ------------------- | --------------------------------------------------------- |
| Pipelines           | Trigger source, status, creation time, VCS metadata       |
| Workflows           | Workflow name, status, duration, pipeline association     |
| Jobs                | Job name, number, status, start/stop times, executor type |
| Workflow jobs       | Jobs scoped to a specific workflow run                    |
| Insights metrics    | Success rate, throughput, mean duration, p95 duration     |
| Insights branches   | Per-branch pipeline metrics and failure counts            |
| Projects            | Project name, slug, VCS type, organization                |
| Specific projects   | Extended project details for a targeted project ID        |
| Contexts            | Context name, created date, environment variable keys     |
| Self IDs            | Authenticated user ID and external identifiers            |
| Self collaborations | Orgs and projects the user collaborates on                |
| Mes                 | User profile, login, analytics tracking ID                |

## Metrics and dimensions

#### Pipeline metrics

| Field         | Type      | Description                                       |
| ------------- | --------- | ------------------------------------------------- |
| id            | String    | Unique pipeline identifier                        |
| state         | String    | Pipeline state (created, errored, etc.)           |
| number        | Integer   | Sequential pipeline number                        |
| created\_at   | Timestamp | When the pipeline was triggered                   |
| trigger\_type | String    | What triggered the pipeline (push, API, schedule) |
| vcs\_branch   | String    | Branch that triggered the pipeline                |
| vcs\_revision | String    | Commit SHA                                        |

#### Workflow metrics

| Field         | Type      | Description                                 |
| ------------- | --------- | ------------------------------------------- |
| id            | String    | Unique workflow identifier                  |
| name          | String    | Workflow name                               |
| status        | String    | Status (success, failed, running, on\_hold) |
| created\_at   | Timestamp | Workflow start time                         |
| stopped\_at   | Timestamp | Workflow end time                           |
| pipeline\_id  | String    | Parent pipeline ID                          |
| project\_slug | String    | Associated project                          |

#### Job metrics

| Field          | Type      | Description                            |
| -------------- | --------- | -------------------------------------- |
| job\_number    | Integer   | Job number within the project          |
| name           | String    | Job name                               |
| status         | String    | Job status (success, failed, canceled) |
| started\_at    | Timestamp | Job start time                         |
| stopped\_at    | Timestamp | Job completion time                    |
| executor\_type | String    | Executor (docker, machine, macos)      |
| dependencies   | Array     | Upstream job dependencies              |

#### Insights metrics

| Field                 | Type    | Description                            |
| --------------------- | ------- | -------------------------------------- |
| success\_rate         | Float   | Percentage of successful pipeline runs |
| throughput            | Float   | Average number of runs per day         |
| mean\_duration\_sec   | Integer | Average run duration in seconds        |
| median\_duration\_sec | Integer | Median run duration                    |
| p95\_duration\_sec    | Integer | 95th percentile duration               |
| total\_runs           | Integer | Total number of runs in the period     |
| failed\_runs          | Integer | Count of failed runs                   |

#### Insights branches

| Field               | Type    | Description                        |
| ------------------- | ------- | ---------------------------------- |
| branch              | String  | Branch name                        |
| success\_rate       | Float   | Success rate for this branch       |
| total\_runs         | Integer | Total pipeline runs on this branch |
| mean\_duration\_sec | Integer | Average duration for this branch   |

## Common metric combinations

* **Workflow + Jobs** — join on `workflow_id` to see which jobs are dragging down workflow duration
* **Pipelines + Insights metrics** — combine to correlate pipeline volume with success rate trends
* **Insights branches + Projects** — spot which branches and projects are failing most often
* **Jobs + Workflows** — use Aggregate to calculate average job duration grouped by workflow name

## Use cases by role

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

* Track deployment frequency and change failure rate across teams
* Monitor pipeline success rates over time to measure CI/CD stability
* Compare workflow duration trends before and after infrastructure changes
* Use Insights metrics to build a DORA-style dashboard in Looker Studio or BigQuery
  {% endtab %}

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

* Identify the slowest jobs using p95 duration data and target them for optimization
* Analyze executor usage across jobs to right-size compute resources
* Pull context data to audit which environment variables are defined per context
* Use Append transformation to combine pipeline data from multiple projects into one report
  {% endtab %}

{% tab title="Development teams" %}

* Review branch-level insights to see which feature branches have the highest failure rates
* Track job failure patterns to catch flaky tests early
* Send pipeline status data to ChatGPT or Claude to auto-generate weekly CI health summaries
  {% endtab %}
  {% endtabs %}

## Platform-specific notes

* **Project ID vs. project slug** — some entities require a `project_id` (UUID from project settings), while others use a `project_slug` (e.g., `gh/myorg/myrepo`). Check the entity's parameter field carefully.
* **Workflow IDs** — you can supply multiple workflow IDs (one per line) to pull data for several workflows in the same data flow source.
* **Job number auto-fetch** — if you don't specify a job number, Coupler.io will auto-fetch it from Workflow jobs, so you only need to set this manually for specific targeted pulls.
* **Start date filtering** — the start date applies to pipeline-based entities. Insights entities have their own aggregation window on the CircleCI side.
* **Rate limits** — CircleCI's API is rate-limited; very large orgs with many pipelines may see slower syncs on first historical load.

## CircleCI common issues

### Connection issues

<details>

<summary>Authentication fails after entering my API token</summary>

Double-check that you're using a **personal API token**, not an OAuth token or a project token. Generate one at CircleCI → User Settings → Personal API Tokens. Make sure you copy the full token without leading or trailing spaces.

</details>

<details>

<summary>Connection succeeds but no data is returned</summary>

This usually means the authenticated user doesn't have access to the org or project you're querying. Confirm that the account associated with the API token is a member of the organization and has at least read access to the relevant projects.

</details>

### Missing data

<details>

<summary>Insights metrics or Insights branches show no rows</summary>

Insights data requires that pipelines have run within the reporting window CircleCI uses on their end. If the project is new or hasn't had recent activity, insights may be empty. Also verify that the `project_id` parameter matches the correct project — a mismatch will silently return nothing.

</details>

<details>

<summary>Jobs entity returns no data</summary>

The Jobs entity requires a job number. If you haven't specified one, Coupler.io will attempt to auto-fetch it from Workflow jobs. Make sure the Workflow jobs entity is included and has data, or manually provide the job number from your pipeline URLs.

</details>

<details>

<summary>Historical data is missing before a certain date</summary>

CircleCI's API has retention limits on older pipeline data depending on your plan. Data beyond the retention window won't be returned regardless of the start date you set. Check your CircleCI plan's data retention policy.

</details>

### Permission errors

<details>

<summary>403 Forbidden error when fetching Contexts</summary>

Context data is restricted to organization admins in many CircleCI plans. If your account is not an org admin, you'll receive a 403. Ask your CircleCI org admin to either grant elevated permissions or pull context data using their token.

</details>

<details>

<summary>Cannot access data for a specific project</summary>

Confirm that the API token belongs to a user who has been granted access to that project in CircleCI. Private projects require explicit project membership — org membership alone may not be sufficient.

</details>

### Data discrepancies

<details>

<summary>Pipeline counts in Coupler.io don't match what I see in the CircleCI dashboard</summary>

The most common cause is the start date cutoff. The CircleCI dashboard may show all-time data while your Coupler.io data flow is scoped to a specific start date. Adjust the start date or check whether the dashboard is applying its own date filters.

</details>

<details>

<summary>Workflow duration looks different from what CircleCI reports</summary>

Coupler.io surfaces raw `created_at` and `stopped_at` timestamps. If you're calculating duration yourself (e.g., in a spreadsheet formula), make sure both fields are being parsed as timestamps in the same timezone. CircleCI timestamps are in UTC.

</details>

### Rate limits

<details>

<summary>Sync is slow or times out on the first historical load</summary>

CircleCI rate-limits API requests. Large organizations with many pipelines will take longer on the initial sync because Coupler.io needs to paginate through all historical records from your start date. Set a more recent start date to reduce the volume of data on the first run, then adjust once everything is working.

</details>

## CircleCI FAQ

<details>

<summary>Which CircleCI plan do I need to use this integration?</summary>

Coupler.io works with any CircleCI plan that provides API access, including the Free plan. However, some data — like advanced Insights metrics — may only be available on Performance or Scale plans depending on your CircleCI subscription.

</details>

<details>

<summary>Where do I find my Project ID?</summary>

Go to your CircleCI project settings. The Project ID appears in the URL: `https://app.circleci.com/settings/project/circleci/ORG_SLUG/PROJECT_ID`. Copy the UUID at the end and paste it into the Project ID parameter in Coupler.io.

</details>

<details>

<summary>Can I pull data from multiple CircleCI projects in one data flow?</summary>

Yes. Add multiple sources to a single data flow — one per project — and use the **Append** transformation to combine them into one unified table at the destination. This is useful for cross-project pipeline dashboards.

</details>

<details>

<summary>Do I need to set a workflow ID or job number?</summary>

For most entities, these are optional. If you don't provide a job number, Coupler.io will attempt to auto-fetch it from the Workflow jobs entity. Workflow IDs are only required if you want to scope data to specific workflows — otherwise, pipeline-level entities return data across all workflows.

</details>

<details>

<summary>Why does the Contexts entity return a permission error?</summary>

Context data in CircleCI is typically restricted to organization admins. If your API token belongs to a non-admin user, you'll see a 403 error. You'll need an org admin to generate the token or grant your account elevated permissions. See the [Common Issues](#circleci-common-issues) article for more detail.

</details>

<details>

<summary>Can I send CircleCI data to an AI tool like ChatGPT or Claude?</summary>

Yes. When setting up your data flow destination, select one of the available AI destinations — ChatGPT, Claude, Gemini, Perplexity, Cursor, or OpenClaw. This lets you feed pipeline metrics, failure trends, or insights data directly into an AI assistant for automated analysis or reporting.

</details>

<details>

<summary>How far back can I pull historical pipeline data?</summary>

This depends on your CircleCI plan's data retention policy. CircleCI limits how far back the API returns records, so very old pipelines may not be available regardless of the start date you configure. For best results, set a start date within your plan's retention window.

</details>

<details>

<summary>What's the difference between Jobs and Workflow jobs?</summary>

Workflow jobs returns all jobs associated with a specific workflow run. Jobs is a more targeted entity that fetches data for a specific job number. In most cases, start with Workflow jobs to get an overview, then use Jobs if you need detailed data for a particular job.

</details>

{% hint style="info" %}
For details on what fields each entity returns, see the [Data Overview](#circleci-data-overview) article. For connection problems or empty results, check [Common Issues](#circleci-common-issues).
{% endhint %}


---

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