---
title: "CircleCI"
canonical_url: "https://docs.getdx.com/connectors/circleci/"
md_url: "https://docs.getdx.com/connectors/circleci.md"
last_updated: "2026-05-08"
---

# CircleCI
By integrating CircleCI with DX, you can analyze pipeline and workflow metrics. Please refer to the API documentation below and our [schema explorer](https://docs.getdx.com/schema/) to see what data DX imports—note that DX does not read or access your source code.

## Prerequisites

To connect CircleCI to DX, you need:

- a CircleCI [Personal Access Token](https://circleci.com/docs/managing-api-tokens/#creating-a-personal-api-token)

## Setup instructions

Follow the steps below to connect CircleCI to DX.

#### Step 1

Create a CircleCI service account (i.e., a GitHub account) for DX.

#### Step 2

In CircleCI, be sure to "Follow" projects that you want to import into DX—only projects that you are following will be imported.

#### Step 3

1. Browse to User Settings.
2. Generate a new API Token.
3. In addition to an API token, you'll need to know your [CircleCI project slug](https://circleci.com/docs/api-intro/#getting-started-with-the-api-v2) which will be a string in a format such as github/dx-eng.

#### Step 4

- Navigate to the connections page in DX and select "+ Connection" in the top right.
- Enter the credentials you have generated in the previous steps—refer to the information below for errors and troubleshooting.

## API reference

The table below lists the specific API endpoints that are used by DX.


| Endpoint | Documentation |
|-----------------------------------------------|---------------|
| /pipeline | [Link](https://circleci.com/docs/api/v2/index.html#operation/listPipelines) |
| /pipeline/{pipelineId}/workflow | [Link](https://circleci.com/docs/api/v2/index.html#operation/listWorkflowsByPipelineId) |
| /project/{projectSlug}/pipeline | [Link](https://circleci.com/api/v2/project/{project-slug}/pipeline) |
| /user/{userId} | [Link](https://circleci.com/docs/api/v2/index.html#tag/User/operation/getUser) |


## Errors

The table below lists potential error codes when adding a connection in DX.


| Error | Description |
|------------------------|--------------------------------------------------------------------------|
| `invalid_credentials` | Your API credentials entered are not valid. |
| `invalid_permissions` | Your API token does not have the permissions required by DX. |
| `no_resources` | DX cannot access any projects or repositories. |


## Curl commands

#### When connection verification fails

When DX verifies a CircleCI connection, it checks if your API token can access pipelines for your organization. If your connection is failing, you can test these endpoints directly using the curl commands below to troubleshoot the issue.

> **Note**: If you're using CircleCI Server (self-hosted), replace `https://circleci.com` in the commands below with your custom CircleCI base URL.

---

#### Step 1: Test organization pipelines

First, test if your token can access pipelines at the organization level. Replace `YOUR_API_TOKEN` with your CircleCI API token and `YOUR_ORG_SLUG` with your organization slug (for example, `gh/your-org`):

```bash
curl -H 'Circle-Token: YOUR_API_TOKEN' \
     -H 'Accept: application/json' \
     'https://circleci.com/api/v2/pipeline?org-slug=YOUR_ORG_SLUG'
```

Expected result: Returns a JSON object with an `items` array containing your pipelines.  
If you get 404 or an empty array, the token might not have access to any pipelines in that organization.

---

#### Step 2: Test project-level pipelines (if Step 1 fails)

If the organization-level endpoint doesn't work, try accessing a specific project's pipelines. Replace `YOUR_API_TOKEN` with your CircleCI API token and `YOUR_PROJECT_SLUG` with your project slug (for example, `gh/your-org/your-repo`):

```bash
curl -H 'Circle-Token: YOUR_API_TOKEN' \
     -H 'Accept: application/json' \
     'https://circleci.com/api/v2/project/YOUR_PROJECT_SLUG/pipeline'
```

Expected result: Returns JSON pipeline data for that project.  
If you get 404, the project hasn’t been followed or built yet, or the token user doesn’t have access to it.

---

#### If Steps 1 and 2 fail

If neither of the above endpoints work, continue with the following diagnostic commands to confirm whether the token is valid, which user it belongs to, and what organizations or projects it can access.

---

#### Step 3: Check the token owner's identity

This verifies that your API token is valid and shows which CircleCI user it belongs to:

```bash
curl -H 'Circle-Token: YOUR_API_TOKEN' \
     'https://circleci.com/api/v2/me'
```

Expected result: Returns user info such as `name`, `login`, and `id`.  
If you get `You are not authorized`, the token is invalid or expired.

---

#### Step 4: List all organizations the token user can access

This lists all GitHub or Bitbucket organizations that the token's owner is a member of in CircleCI:

```bash
curl -H 'Circle-Token: YOUR_API_TOKEN' \
     'https://circleci.com/api/v2/me/collaborations'
```

Expected result: Returns an array of orgs that the token can access. If your target org isn’t listed, the user doesn’t have access to that org’s pipelines.

---

#### Step 5: List projects visible to the token user

This shows all projects that the token user has "followed" or can access in CircleCI:

```bash
curl -H 'Circle-Token: YOUR_API_TOKEN' \
     'https://circleci.com/api/v2/project'
```

Expected result: Returns a list of project slugs. If you get `Not Found`, the user hasn’t followed any projects yet.  
To fix this, log into CircleCI as that user and click **“Follow Project”** on the relevant repo. After doing so, the `/project/.../pipeline` and `/pipeline?org-slug=...` endpoints should start returning valid data.
---

## Sitemap

[Overview of all docs pages](/llms.txt)