# How to Integrate Retool with CircleCI

- Tool: Retool
- Difficulty: Intermediate
- Time required: 20 minutes
- Last updated: April 2026

## TL;DR

Use CircleCI with Retool by creating a REST API Resource using your CircleCI personal API token for Bearer authentication. The base URL is https://circleci.com/api/v2. Build a pipeline monitoring dashboard that shows build status across projects, view job logs, and trigger pipeline runs directly from Retool — giving engineering teams a centralized CI/CD operations panel.

## Build a CircleCI CI/CD Monitoring Dashboard in Retool

Engineering and DevOps teams rely on CircleCI as the backbone of their software delivery pipeline, but CircleCI's native dashboard is designed for individual developers monitoring their own builds. Platform engineering teams managing multiple projects, release managers overseeing deployment gates, and DevOps engineers monitoring pipeline health across a whole organization need a cross-project view that CircleCI's interface doesn't provide efficiently.

CircleCI's API v2 offers comprehensive programmatic access to pipelines, workflows, jobs, artifacts, and test results. With a personal API token or project API key, Retool can query all of this data and display it in a unified monitoring panel. The server-side proxy ensures tokens never reach the browser, and Retool's event handlers make it straightforward to add approval workflow logic — for example, requiring a Retool form submission before triggering a production deployment.

The most valuable Retool + CircleCI pattern is a deployment dashboard: a single screen showing the current state of all pipelines across critical projects, with workflow status, recent test results, and one-click buttons to trigger rebuilds or approve holds — eliminating the need to navigate between GitHub, CircleCI, and deployment tools during a release.

## Before you start

- A CircleCI account with access to the projects you want to monitor
- A CircleCI personal API token (generated from User Settings → Personal API Tokens in CircleCI)
- Project slugs for the CircleCI projects to monitor (format: github/org/repo or bitbucket/org/repo)
- A Retool account with permission to create Resources
- Basic familiarity with Retool's query editor, Table component, and event handlers

## Step-by-step guide

### 1. Generate a CircleCI personal API token

In CircleCI, click your profile avatar (top-right corner) → User Settings → Personal API Tokens. Click Create New Token. Give it a descriptive name like 'Retool Dashboard' and click Add API Token. Copy the token immediately — CircleCI only shows it once.

The personal API token grants access to all organizations and projects your CircleCI account belongs to, with the same permissions as your user account. This is appropriate for internal Retool tools. If you need to restrict access to a specific project, CircleCI also offers project API keys (under Project Settings → API Permissions) — these are scoped to a single project and use the same Bearer token pattern.

CircleCI's API v2 (https://circleci.com/api/v2) is the current version and the one you should use for all new integrations. The older v1.1 API is deprecated for many endpoints. The API uses project slugs to identify projects — the format is {vcs}/{organization}/{repository} (e.g., 'github/myorg/myapp' or 'bitbucket/myorg/backend').

Store the token securely — in Retool, use Configuration Variables (Settings → Configuration Variables) with the secret flag enabled so the token is never exposed in the browser. Rotate the token if it's ever accidentally exposed, and create a new one with a fresh name.

**Expected result:** You have a CircleCI personal API token and know the project slugs (vcs/org/repo) for the projects you want to monitor in Retool.

### 2. Create the CircleCI REST API Resource in Retool

In Retool, navigate to the Resources tab and click Add Resource. Select REST API.

Configure the resource:
- Name: CircleCI API
- Base URL: https://circleci.com/api/v2

For authentication, select Bearer Token from the Authentication dropdown. Enter your CircleCI personal API token in the Token field. If stored in Configuration Variables: {{ retoolContext.configVars.CIRCLECI_API_TOKEN }}.

Add an Accept header: Key: Accept, Value: application/json. This ensures CircleCI returns JSON responses.

Add a Content-Type header: Key: Content-Type, Value: application/json. This is needed for POST requests (triggering pipelines, approving workflows).

Click Create Resource. Test the connection by creating a query with method GET and path /me. This endpoint returns your CircleCI user information. If it returns your user details (name, login, email), the authentication is working correctly. A 401 response indicates an incorrect or expired token.

**Expected result:** The CircleCI API resource is configured and a test GET /me returns your CircleCI user profile including name and login information.

### 3. Fetch pipelines and workflow status

Create a query named getPipelines with method GET and path /project/{{ select_project.value }}/pipeline. The select_project.value should be the CircleCI project slug (e.g., 'github/myorg/myapp').

Add parameters:
- branch: {{ textInput_branch.value || 'main' }} (filter to a specific branch)
- page-token: {{ pagination.nextToken || '' }} (CircleCI uses cursor-based pagination with page tokens)

The response includes an items array of pipeline objects. Each pipeline has: id, number, state (created/errored/setup-pending), trigger (type: push/scheduled/api, actor), vcs (branch, revision, commit.subject, commit.author_login), created_at, and errors.

To get workflow status for each pipeline, you need a second query. Create a getPipelineWorkflows query with path /pipeline/{{ table_pipelines.selectedRow.data.id }}/workflow. This returns the workflows that ran for the selected pipeline, each with: id, name, status (running/succeeded/failed/canceled/on_hold/unauthorized), pipeline_id, created_at, and stopped_at.

Create a transformer that merges pipeline and workflow data for the main monitoring Table, showing the combined status of each pipeline's primary workflow.

```
// Transformer for pipeline display
const pipelines = data.items || [];
return pipelines.map(pipeline => ({
  id: pipeline.id,
  number: pipeline.number,
  state: pipeline.state,
  branch: pipeline.vcs?.branch || '',
  revision: (pipeline.vcs?.revision || '').substring(0, 7),
  commit_message: pipeline.vcs?.commit?.subject || '',
  author: pipeline.vcs?.commit?.author_login || pipeline.trigger?.actor?.login || '',
  trigger_type: pipeline.trigger?.type || '',
  created_at: pipeline.created_at
    ? new Date(pipeline.created_at).toLocaleString()
    : '',
  state_icon: pipeline.state === 'created' ? '✓'
    : pipeline.state === 'errored' ? '✗' : '⟳'
}));
```

**Expected result:** The getPipelines query populates a Table showing recent pipelines for the selected project with branch, commit, trigger type, and creation time.

### 4. Fetch job details and build logs

Create a getWorkflowJobs query with method GET and path /workflow/{{ table_workflows.selectedRow.data.id }}/job. This returns all jobs in the selected workflow with their status, duration, and resource allocation.

Each job object includes: id, name, status (running/success/failed/blocked/canceled/unauthorized), started_at, stopped_at, job_number, type (build/approval), and dependencies.

For jobs with status 'failed', you'll want to surface the failure reason. CircleCI's API v2 provides job details via /project/{projectSlug}/job/{jobNumber} — this returns more detailed step information but not the raw log content.

For accessing actual job log output, use the job artifacts endpoint: GET /project/{projectSlug}/{jobNumber}/artifacts returns a list of artifact files, which can include test results (JUnit XML), coverage reports, and custom outputs you've stored in CircleCI artifacts.

Create a getJobArtifacts query with path /project/{{ select_project.value }}/{{ table_jobs.selectedRow.data.job_number }}/artifacts. Each artifact has a path and a url — use these URLs in a Table to link to the artifact files directly.

For the approval workflow use case, jobs with type: 'approval' and status: 'on_hold' are waiting for manual approval. Wire an Approve button to POST /workflow/{workflowId}/approve with body: {"approval_request_id": "{{ table_jobs.selectedRow.data.id }}"}.

```
// Transformer for workflow jobs
const jobs = data.items || [];
return jobs.map(job => {
  const duration = job.started_at && job.stopped_at
    ? Math.round((new Date(job.stopped_at) - new Date(job.started_at)) / 1000)
    : null;
  return {
    id: job.id,
    job_number: job.job_number,
    name: job.name,
    status: job.status,
    type: job.type,
    started_at: job.started_at ? new Date(job.started_at).toLocaleString() : 'Not started',
    duration_seconds: duration,
    duration_display: duration ? `${Math.floor(duration / 60)}m ${duration % 60}s` : '--',
    is_approval: job.type === 'approval',
    needs_approval: job.type === 'approval' && job.status === 'blocked'
  };
});
```

**Expected result:** The workflow jobs Table shows all jobs in the selected workflow with status, duration, and action buttons for approval jobs.

### 5. Build pipeline trigger and monitoring automation

To trigger a new CircleCI pipeline from Retool, create a triggerPipeline query with method POST and path /project/{{ select_project.value }}/pipeline. The request body should be JSON:

{"branch": "{{ textInput_branch.value || 'main' }}", "parameters": {{ textArea_params.value ? JSON.parse(textArea_params.value) : {} }}}

Pipeline parameters must match parameters declared in your .circleci/config.yml file. If no parameters are needed, use {"branch": "{{ textInput_branch.value }}"} without a parameters field.

After triggering, the response includes the new pipeline ID and number. Set up an event handler: On Success → Run getPipelines to refresh the pipeline Table so the newly triggered pipeline appears.

For a comprehensive monitoring dashboard, build a Stat panel at the top showing:
- Last build status (pass/fail for the most recent completed workflow on main)
- Build frequency (count of pipelines triggered today)
- Mean test duration (average of stopped_at - started_at across recent successful jobs)
- Current running builds (count of pipelines with status 'running')

For teams that need automated deployment gates, RapidDev's team can help build Retool Workflows that combine CircleCI status polling with Slack notifications and database-backed approval audit trails.

```
// Pipeline trigger request body
{
  "branch": "{{ textInput_branch.value || 'main' }}",
  "parameters": {
    "deploy_env": "{{ select_environment.value || 'staging' }}",
    "run_integration_tests": {{ toggle_integrationTests.value ? 'true' : 'false' }}
  }
}
```

**Expected result:** The Retool dashboard supports triggering new CircleCI pipelines with custom parameters, and the pipeline Table refreshes automatically to show the new pipeline's progress.

## Best practices

- Store your CircleCI API token in Retool Configuration Variables marked as secret — personal API tokens give full account access and should never be hardcoded in query parameters or visible to the browser.
- Use project API keys (scoped to a single project) instead of personal API tokens when building dashboards for a specific project team — this limits the blast radius if the key is compromised.
- Handle CircleCI's cursor-based pagination explicitly — unlike offset pagination, you must capture and forward the next_page_token from each response to load subsequent pages.
- Build approval confirmation dialogs using Retool modal components before executing approval or cancellation actions — these are irreversible operations that affect live deployments.
- Filter pipeline queries to specific branches (main, release, develop) rather than fetching all branches — this dramatically reduces response times for repositories with many active branches.
- Cache pipeline status queries with a short TTL (30-60 seconds) if auto-refreshing — CircleCI's API has rate limits and rapid polling can exhaust them quickly.
- When building multi-project dashboards, use a JavaScript query with Promise.all to fetch pipeline status for all projects in parallel rather than sequentially — this keeps dashboard load times acceptable as you add more projects.
- Add an audit log table (backed by your database) for pipeline triggers and deployment approvals performed through Retool — record who triggered what and when for compliance and incident review.

## Use cases

### Build a cross-project pipeline status dashboard

Create a Retool dashboard showing the current pipeline status across multiple CircleCI projects simultaneously. Engineering leads can see at a glance which projects have passing builds, which have failed workflows, and which are currently running — with drill-down to the specific failing job without opening the CircleCI UI.

Prompt example:

```
Build a Retool CircleCI monitoring dashboard. Show a Table of recent pipelines across selected projects with columns for project name, pipeline number, branch, trigger type (push/API/schedule), commit message, workflow status (running/succeeded/failed), and elapsed time. Color-code the status column (green=success, red=failed, yellow=running). Add a Refresh button and an auto-refresh toggle. Include a Select for filtering by project.
```

### Build a deployment gate and approval workflow

Build a Retool panel that serves as the approval interface for CircleCI deployment holds. When a pipeline reaches a manual approval step, the pending hold appears in Retool where an authorized team member can review the test results and approve or cancel the deployment — replacing the need to log into CircleCI directly.

Prompt example:

```
Build a Retool deployment approval panel. Show all CircleCI workflows currently in 'on_hold' status across production projects. For each held workflow, display the project name, branch, last commit author, workflow ID, and a summary of passed and failed tests from the previous job. Include an Approve button and a Cancel button. Wire Approve to POST /workflow/{id}/approve and Cancel to POST /workflow/{id}/cancel.
```

### Build a pipeline trigger and configuration tool

Create a Retool tool that lets authorized team members trigger CircleCI pipelines manually with custom parameters — for example, triggering a release build for a specific version tag, running a subset of test suites, or kicking off a deployment to a specific environment — without needing CircleCI access or knowing the exact API call.

Prompt example:

```
Build a Retool pipeline trigger panel. Show a Select for choosing the project, a Select for branch, and input fields for pipeline parameters (target_environment, run_tests, version_tag). Add a Trigger Pipeline button that POSTs to CircleCI's trigger endpoint with the configured parameters. Show the resulting pipeline URL and current status after triggering. Include a log of recently triggered pipelines with who triggered them.
```

## Troubleshooting

### GET /project/{slug}/pipeline returns 404 Not Found

Cause: The project slug format is incorrect or the project doesn't exist with that slug in your CircleCI account.

Solution: Verify the project slug format is exactly {vcs-type}/{org}/{repo} — for example 'github/mycompany/backend-api'. Check the project URL in CircleCI to confirm the exact org and repo names (case-sensitive). For Bitbucket projects, use 'bitbucket' instead of 'github' as the VCS prefix. Navigate to your project in CircleCI and copy the slug from the URL to avoid typos.

### Pipeline trigger (POST /pipeline) returns 400 Bad Request

Cause: The pipeline parameters in the request body don't match the parameter definitions in the .circleci/config.yml file, or a required parameter is missing.

Solution: Open your .circleci/config.yml and check the parameters section at the top of the file. Ensure every parameter name, type (string/boolean/integer), and default value in your Retool request body matches the YAML definition exactly. If the pipeline has no declared parameters, send the trigger request without a parameters field rather than with an empty object.

### Workflow approval POST returns 404 or 'workflow not found'

Cause: The workflow ID used for the approval request may be incorrect, or the approval step has already been actioned (approved or canceled).

Solution: Verify you're using the workflow ID (a UUID) not the pipeline ID for the approval endpoint. The approval endpoint is /workflow/{workflowId}/approve, not /pipeline/{id}/approve. Check that the job status is still 'blocked' — if it's changed to 'canceled' or 'success', the approval window has closed. Refresh getWorkflowJobs to confirm the current job status before approving.

### Pagination stops working after the first page of pipelines

Cause: CircleCI v2 uses cursor-based pagination with a next_page_token field in the response, not offset-based page numbers.

Solution: In the response from getPipelines, check for the next_page_token field at the top level of the response object (alongside the items array). Pass this token as the page-token query parameter in the next request. In Retool, store the next_page_token in a variable and use it to build a 'Load More' button that triggers the next page query.

```
// Store pagination token in a Retool variable
// After getPipelines runs, set nextPageToken.setValue(getPipelines.data.next_page_token)
```

## Frequently asked questions

### Does Retool have a native CircleCI connector?

Yes, Retool does list CircleCI as a native connector in some versions. However, you can also connect via a REST API Resource using CircleCI's personal API token as Bearer authentication against the v2 API. The REST API Resource approach gives you full flexibility over which endpoints to call and how to transform the data.

### Can I trigger CircleCI pipelines that require approval gates from Retool?

Yes. CircleCI approval jobs appear as workflows in 'on_hold' status with individual jobs of type 'approval' in 'blocked' state. Query GET /workflow/{workflowId}/job to find pending approval jobs, then POST /workflow/{workflowId}/approve with the approval_request_id to trigger the approval. This makes Retool a natural interface for deployment approval workflows where managers review build status before approving production releases.

### What project slug format does CircleCI's API use?

CircleCI v2 identifies projects with slugs in the format {vcs-type}/{organization}/{repository} — for example 'github/mycompany/backend-api' or 'bitbucket/myorg/frontend'. This is different from the numeric project IDs used in CircleCI's v1.1 API. Find your project slug by navigating to the project in CircleCI and reading the URL, or use the GET /me/projects endpoint to list all projects with their slugs.

### How do I fetch test results and artifacts from CircleCI builds?

Use GET /project/{projectSlug}/{jobNumber}/artifacts to list artifact files for a specific job. Each artifact has a URL you can link to in your Retool Table. For JUnit test results specifically, CircleCI stores them in artifacts when configured in your config.yml with the store_test_results step. Access these as standard artifacts. Note that raw log output requires a separate download via the artifact URL.

### Can Retool automatically monitor CircleCI and send alerts when builds fail?

Yes, using Retool Workflows with a scheduled trigger. Create a Workflow that runs every 5-10 minutes, queries CircleCI for pipelines with failed workflow status, compares against a stored list of previously alerted failures, and triggers a Slack or email notification for new failures. This creates a lightweight build monitoring bot without requiring CircleCI webhooks or additional infrastructure.

---

Source: https://www.rapidevelopers.com/retool-integrations/circleci
© RapidDev — https://www.rapidevelopers.com/retool-integrations/circleci