View all connectors

CircleCI

By integrating CircleCI with DX, you can analyze pipeline and workflow metrics. Please refer to the API documentation below and our schema explorer 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:

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 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
/pipeline/{pipelineId}/workflow Link
/project/{projectSlug}/pipeline Link
/user/ Link

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):

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):

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:

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:

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:

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.