For the complete documentation index, see llms.txt. This page is also available as Markdown.

Circleci

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

  • Your organization slug and project IDs (available in CircleCI project settings URLs)

Quick start

How to connect

1

Create a new data flow. In Coupler.io, click Add data flow and search for CircleCI as your source.

2

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.

3

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.

4

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.

5

Choose a destination. Select where your data should land — Google Sheets, Excel, BigQuery, Looker Studio, or an AI destination like ChatGPT, Claude, or Gemini.

6

Run the data flow. Click Run to execute a manual sync and verify your data loads correctly.

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

  • 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

  • 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

  • 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

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

Authentication fails after entering my API token

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.

Connection succeeds but no data is returned

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.

Missing data

Insights metrics or Insights branches show no rows

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.

Jobs entity returns no data

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.

Historical data is missing before a certain date

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.

Permission errors

403 Forbidden error when fetching Contexts

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.

Cannot access data for a specific project

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.

Data discrepancies

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

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.

Workflow duration looks different from what CircleCI reports

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.

Rate limits

Sync is slow or times out on the first historical load

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.

CircleCI FAQ

Which CircleCI plan do I need to use this integration?

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.

Where do I find my Project ID?

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.

Can I pull data from multiple CircleCI projects in one data flow?

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.

Do I need to set a workflow ID or job number?

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.

Why does the Contexts entity return a permission error?

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 article for more detail.

Can I send CircleCI data to an AI tool like ChatGPT or Claude?

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.

How far back can I pull historical pipeline data?

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.

What's the difference between Jobs and Workflow jobs?

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.

For details on what fields each entity returns, see the Data Overview article. For connection problems or empty results, check Common Issues.

Last updated

Was this helpful?