Menu

Mattering Automations CircleCI integration

Connect CircleCI to Mattering Automations: pipelines, workflows and jobs, artifacts and test metadata, pipeline triggers, cancel and rerun, project and context environment variables, checkout keys, scheduled pipelines, outbound webhooks, and the Insights reporting family as workflow steps, authenticated with one personal API token.

The Mattering Automations CircleCI integration adds the CircleCI API v2 to your automation canvas: list and read pipelines by id or by the number shown in the web app, fetch the source and compiled config a run actually used, walk a pipeline down through its workflows to individual jobs, pull job artifacts and per-test metadata, start runs through either trigger endpoint, cancel and rerun work in flight, manage project environment variables, contexts and context variables, checkout keys, scheduled pipelines and outbound webhooks, and read the Insights family from project and organization summaries down to job timeseries and flaky tests.

The credential is a CircleCI personal API token, created in the CircleCI web app under User Settings, then Personal API Tokens. CircleCI accepts it either as a Bearer authorization header, which its API developer's guide recommends, or as the CircleCI-specific Circle-Token header that existing integrations widely use; both reach the same v2 endpoints, and this connector sends Circle-Token. CircleCI's API documentation states that project API tokens are not supported on API v2, so a personal token is the only credential that works, and there is no OAuth app flow for authenticating REST API v2 calls. Setup takes a few minutes, and this guide walks through each step and ends with the full node reference.

The safety modeling is stated on the nodes rather than buried. Of the 55 nodes, 36 read and 19 act, and six carry a destructive flag: CircleCI: Delete Env Var, CircleCI: Delete Context Env Var, CircleCI: Delete Context, CircleCI: Delete Checkout Key, CircleCI: Delete Schedule and CircleCI: Delete Webhook. Three more deserve the same care for a different reason: CircleCI: Trigger Pipeline, CircleCI: Trigger Pipeline Run and CircleCI: Rerun Workflow queue real compute against the organization's plan usage and execute whatever the config says, including deploy jobs, so rerunning a release workflow deploys again. Runs they start can be stopped with CircleCI: Cancel Workflow or CircleCI: Cancel Job.

Before you start

  • A CircleCI account with access to the projects you want to automate. CircleCI offers a free plan and does not document API v2 access as plan gated, so an account on any plan with a personal API token can exercise the read surface. Runs that the trigger and rerun nodes start consume the organization's plan usage like any other run; check circleci.com/pricing for current plan details rather than assuming an allowance.
  • Permission to create a personal API token in User Settings, then Personal API Tokens. The token is created against a user account rather than a project, CircleCI documents it as granting full read and write permissions with no scopes to narrow, and it acts as the person who created it, so if your team separates duties, connect with an account whose reach matches what the automations should be allowed to touch.
  • At least one project slug to point the first workflows at, copied from Project Settings, then Overview in CircleCI. CircleCI API v2 has no project listing endpoint, so the slug is something you copy once rather than something a picker can discover for you.
  • For the webhook and pipeline definition nodes, the project id (a UUID). CircleCI: Get Project returns it from the project slug, so there is nothing to look up by hand.
  • A Mattering workspace with access to the Automations app.
  • Not usable here: project API tokens. CircleCI states in its API documentation that project API tokens are not supported for API v2, so a personal API token is the only credential this integration can use.

Create your CircleCI personal API token

Mattering authenticates to CircleCI with a personal API token on every request to circleci.com/api/v2. CircleCI accepts it either as a Bearer authorization header, which its API developer's guide recommends, or as the CircleCI-specific Circle-Token header that existing integrations widely use; both reach the same v2 endpoints, and this connector sends Circle-Token. There is no OAuth app flow for authenticating REST API v2 calls. The token is created against a user account rather than a project, CircleCI documents it as granting full read and write permissions with no scopes to narrow, and it acts as the person who created it, which keeps setup short and makes the choice of account the real access decision.

Sign in to the CircleCI web app and open User Settings, then Personal API Tokens.
Click Create New Token, give it a name that identifies this integration, and create it.
Copy the token while it is on screen. CircleCI shows the full value at creation and does not display it again, so a token you failed to copy has to be replaced rather than recovered.
This is a personal API token, not a project API token. Project tokens are not supported on API v2 and will fail here even though they look like valid CircleCI credentials. If Test Connection returns 401 with a credential you are sure about, check which kind of token you copied.

Connect CircleCI to Mattering

In Mattering Automations, open Connectors and click Add Connector.
Choose CircleCI from the list.
Click Create new credential, paste the personal API token, and save.
The credential is stored encrypted in Google Secret Manager and never appears in workflow logs. The token is registered with the run's redaction context, so it stays masked in node output as well.
Click Test Connection. Mattering calls CircleCI's current user endpoint, which every valid personal token can call and which takes no parameters: a user record proves the credential, and a 401 with the message about logging in first means the token is wrong or has been revoked.
Click Connect. All 55 CircleCI nodes appear in your canvas palette.

Verify it works

After connecting, open any automation canvas and check the palette: a CircleCI section should list the query and action nodes. Drop CircleCI: Get Current User onto the canvas and run a test step. It is the integration's natural probe: it takes no parameters, every valid personal token can call it, and it returns the account the token belongs to, which is also how you confirm you connected with the account you meant to. Next run CircleCI: List Collaborations and note the shape, a bare JSON array rather than the usual page envelope, so the organization slugs sit at data[].slug. Those slugs are what the context and organization metrics nodes ask for.

Then point the integration at a real project. Paste a project slug from Project Settings, then Overview into CircleCI: Get Project and run it: the response carries the project name, default branch and the project id at data.id, which is the value the webhook nodes want as their scope id and the pipeline definition lister wants as its project id. Finish with CircleCI: List Project Pipelines, which returns pipelines newest first with their ids and numbers at data.items[].id, the entry point for every workflow and job drill-down in this integration. Everything in this verify path is read-only: it cannot reach the six destructive nodes and cannot start a run, so it is safe to re-run whenever you rotate the token.

Node reference

55 nodes, generated from the connector itself so this reference always matches what ships.

Read and query nodes 36

CircleCI: Get Checkout Key

circleci_get_checkout_key

Fetch one checkout key by fingerprint: its public key, type, preferred flag and creation time. Both md5 and sha256 fingerprints work; the runner URL-encodes whichever is given.

CircleCI: Get Context

circleci_get_context

Fetch a context by id: its name and creation time. Values are never included here; use List Context Env Vars for the variable names inside it.

CircleCI: Get Current User

circleci_get_current_user

Return the user the stored personal API token belongs to: id, login and display name. Takes no parameters and works for every valid token, so this is the credential health check to run first in any CircleCI automation. An invalid token gets 401 with a plain message and no secret is echoed back.

CircleCI: Get Env Var

circleci_get_env_var

Fetch one project environment variable by name. The value is MASKED (four x characters plus the last four characters), so this answers whether a variable exists and roughly which value is set, never what the secret is.

CircleCI: Get Flaky Tests

circleci_get_flaky_tests

List a project's flaky tests: tests that passed and failed on the same commit. Each row names the test, its class and file, the job and workflow it flaked in, the pipeline and job numbers, how many times it has flaked and how much time that wasted; the response also carries a count of unique flaky tests. Flaky tests are branch agnostic, and a test drops off this list after two weeks without a new flake.

CircleCI: Get Job

circleci_get_job

Fetch a job's metadata by its UUID: name, job number, type, status, start and stop times, and the project, pipeline and workflow ids it belongs to. Use the job number it returns with the artifact and test metadata nodes.

CircleCI: Get Job Artifacts

circleci_get_job_artifacts

List the artifacts a job stored, each with its path inside the artifact tree, the parallel node index that produced it, and a download URL. Those URLs are what a following HTTP node fetches, using the same CircleCI token. Only jobs with a store_artifacts step return anything.

CircleCI: Get Job Details

circleci_get_job_details

Fetch the full detail record for a job by project slug and job number: web URL, project and organization, executor type and resource class, parallelism and per-run statuses, contexts used, queued, started and stopped times and the duration in milliseconds. This is the richest job read and the one to use for run-time and resource reporting.

CircleCI: Get Job Test Metadata

circleci_get_job_test_metadata

Return the per-test records a job uploaded through store_test_results: test name, class name, source file, result, run time and any failure message. Only jobs with a store_test_results step return rows, and only in the formats CircleCI parses.

CircleCI: Get Job Timeseries

circleci_get_job_timeseries

Timeseries metrics for every job in a workflow, bucketed hourly or daily: each row is one job in one interval with its run counts, throughput, duration statistics and indicative credits, plus the interval timestamp and the first and last execution times inside it. Retention differs by granularity: hourly buckets are kept for 48 hours, daily buckets for 90 days, and one request can span at most 90 days. Poll this sparingly; frequent polling is a documented way to get throttled.

CircleCI: Get Org Summary Metrics

circleci_get_org_summary_metrics

Organization level summary metrics and trends: total runs, total duration, success rate, throughput and indicative credits for the whole org and for each project in it, plus the list of project names. Note that all_projects returns project NAMES, which are not project slugs and cannot be used directly in project-scoped nodes.

CircleCI: Get Pipeline

circleci_get_pipeline

Fetch one pipeline by its UUID: number, state, project slug, trigger and actor, VCS branch or tag and revision, plus any config errors or warnings CircleCI recorded when it compiled the pipeline. Errors here are why a pipeline can exist and still run nothing.

CircleCI: Get Pipeline By Number

circleci_get_pipeline_by_number

Fetch one pipeline by the number shown in the CircleCI web app and in commit statuses, without needing its UUID. Same payload as Get Pipeline.

CircleCI: Get Pipeline Config

circleci_get_pipeline_config

Return the configuration a pipeline actually ran: source is the .circleci/config.yml as committed, compiled is the fully expanded config after orbs, parameters and matrix expansion. Setup workflows additionally fill setup-config and compiled-setup-config. The compiled text is the one to diff when a run behaves differently from what the file suggests.

CircleCI: Get Project

circleci_get_project

Fetch a project by slug: its name, project id (UUID), organization name, slug and id, and VCS info including the repository URL and default branch. The project id returned here is what the webhook nodes need as their scope id and what the pipeline definition listing needs as its project id.

CircleCI: Get Project Summary Metrics

circleci_get_project_summary_metrics

Project level summary metrics and trends across every workflow and branch: total runs, total duration, success rate, throughput and indicative credits, broken out per workflow and per workflow/branch pair, plus the full lists of branch names and workflow names the project has. Runs going back at most 90 days are aggregated and trends cover at most 30 days. The all_workflows list this returns is what the workflow name pickers elsewhere in this connector read.

CircleCI: Get Schedule

circleci_get_schedule

Fetch one scheduled pipeline by id: name, description, timetable, parameters, attribution actor and timestamps. Available only for schedules on GitHub OAuth and Bitbucket Cloud pipeline definitions.

CircleCI: Get Webhook

circleci_get_webhook

Fetch one outbound webhook by id: name, URL, events, TLS verification flag, scope and timestamps. The signing secret is masked.

CircleCI: Get Workflow

circleci_get_workflow

Fetch one workflow by id: name, status, the pipeline it belongs to and that pipeline's number, the project slug, who started it, and its created and stopped times. The status field is what a polling automation watches to decide a run finished.

CircleCI: Get Workflow Job Metrics

circleci_get_workflow_job_metrics

Summary metrics for each JOB inside one workflow over the chosen reporting window: run counts, success rate, duration statistics, throughput and indicative credits, each row carrying the window it covers. Filter to one job by name or by a substring of it. This is where a slow or flaky step shows up against the rest of the workflow.

CircleCI: Get Workflow Metrics

circleci_get_workflow_metrics

Summary metrics for each of a project's workflows over the chosen reporting window: total, successful and failed runs, success rate, mean time to recovery, throughput, duration min/mean/median/p95/max and indicative credits, each row carrying the window it was computed over. Scoped to the default branch unless a branch is given or all branches is set. Metrics refresh daily, so the last 24 hours may be missing.

CircleCI: Get Workflow Runs

circleci_get_workflow_runs

List recent runs of one workflow, newest first: run id, branch, status, duration in seconds, created and stopped times, indicative credits used and whether the run was an approval. Runs going back at most 90 days are available, and one request can cover at most 90 days between the start and end dates. This is the per-run detail behind the workflow metrics.

CircleCI: Get Workflow Summary

circleci_get_workflow_summary

Metrics and trends for ONE workflow: run counts, success rate, mean time to recovery, throughput, duration statistics and indicative credits, alongside trend values for each. Use this for a single workflow health card; use Get Workflow Metrics when you want every workflow at once.

CircleCI: List Checkout Keys

circleci_list_checkout_keys

List the SSH checkout keys a project uses to clone code: public key, type (deploy-key or github-user-key), fingerprint, whether it is the preferred key, and when it was created. Only public material is returned.

CircleCI: List Collaborations

circleci_list_collaborations

List the organizations the token's user belongs to or can collaborate on, across VCS providers, each with its org slug (gh/example-org), name, id and VCS type. This is the org discovery call: it returns ORGANIZATIONS, not projects, so it feeds org-scoped nodes such as Get Org Summary Metrics and the context listing. The response is a bare JSON array, so output paths start at data[].

CircleCI: List Context Env Vars

circleci_list_context_env_vars

List the environment variables in a context: variable name, context id, created and updated times. Values are NOT returned at all, not even masked, so this is a safe audit read of what a context provides.

CircleCI: List Contexts

circleci_list_contexts

List an organization's contexts with their ids, names and creation times. Identify the owner by slug (gh/example-org) or by organization id; pass one, not both. Context ids from here drive every context environment variable node.

CircleCI: List Env Vars

circleci_list_env_vars

List a project's environment variables. Values come back MASKED, exactly as the web app shows them: four x characters plus the last four characters of the real value. Use this to audit which names exist, never to read a secret back out.

CircleCI: List Insights Branches

circleci_list_insights_branches

List the branches Insights currently holds data for, optionally narrowed to the branches one workflow ran on. At most 5,000 branches are returned. This is the branch discovery call the branch pickers on the other insights nodes read from.

CircleCI: List My Pipelines

circleci_list_my_pipelines

List only the pipelines in this project that the token's own user triggered. Same item shape as List Project Pipelines. Useful for a personal automation that should react to its own runs and ignore everyone else's.

CircleCI: List Pipeline Definitions

circleci_list_pipeline_definitions

List a project's pipeline definitions: the named config entry points shown in Project Settings > Pipelines, each with its id, name, the repository and file path its config is read from, and the repository its checkout step clones. The definition id is what Trigger Pipeline Run requires.

CircleCI: List Pipeline Workflows

circleci_list_pipeline_workflows

List the workflows a pipeline started, each with its id, name, status (success, running, failing, on_hold, canceled and the rest), who started or canceled it, and its created and stopped timestamps. Workflow ids from here drive the cancel, rerun and job listing nodes.

CircleCI: List Project Pipelines

circleci_list_project_pipelines

List a project's pipelines newest first, optionally limited to one branch. Each item carries the pipeline id and number, its state, the trigger that started it (api, webhook, explicit or scheduled_pipeline) and the VCS revision and commit. This is the entry point for every pipeline, workflow and job drill-down in this connector.

CircleCI: List Schedules

circleci_list_schedules

List a project's scheduled pipeline triggers with their id, name, description, timetable, pipeline parameters and the actor runs are attributed to. CircleCI documents this as covering schedules on GitHub OAuth and Bitbucket Cloud pipeline definitions only; GitHub App schedules live under pipeline definition triggers instead.

CircleCI: List Webhooks

circleci_list_webhooks

List the outbound webhooks registered on a project: id, name, target URL, events, TLS verification flag and scope. The signing secret comes back masked. Webhooks are project-scoped: pass the project id as the scope id and project as the scope type, which is the only type CircleCI currently supports.

CircleCI: List Workflow Jobs

circleci_list_workflow_jobs

List the jobs in a workflow with their id, name, job number, status, type (build or approval), start and stop times and the jobs they depend on. Approval jobs carry an approval request id and no job number, since they gate rather than run. Job ids and numbers from here drive the job detail, artifact, test and cancel nodes.

Action nodes 19

CircleCI: Cancel Job

circleci_cancel_job

Cancel one running job by project slug and job number. The job ends in the canceled state and its workflow continues or fails according to the config; the job record and its logs stay. Nothing is deleted and the work can be redone with Rerun Workflow. Side effects a job already completed are not undone.

CircleCI: Cancel Workflow

circleci_cancel_workflow

Cancel a running workflow. Jobs still running stop, queued jobs never start, and the workflow ends in the canceled state; the record and its logs stay. Nothing is deleted and the workflow can be started again with Rerun Workflow. Work that a deploy job already completed is not undone by cancelling.

CircleCI: Create Checkout Key

circleci_create_checkout_key

Create a checkout key for the project and return its public half and fingerprint. A deploy-key reaches only this repository; a user-key acts as the authorizing user and reaches every repository that user can read, so prefer deploy-key unless a job must clone a second private repo. CircleCI documents this call as usable only with a personal API token, and not for GitLab or GitHub App projects. Adding a key does not remove the existing one.

CircleCI: Create Context

circleci_create_context

Create an empty context in an organization and return its id. A context is a named bundle of environment variables that jobs opt into from the config file. Identify the owner by slug or by organization id, not both. Creating a context changes nothing that already runs; jobs only see it once the config names it.

CircleCI: Create Env Var

circleci_create_env_var

Create a project environment variable, or overwrite the value of one that already exists under the same name. Every job in the project can read it, so treat it as a project wide secret. The response echoes the masked value only. Overwriting replaces a value that cannot be read back first, so check List Env Vars before reusing a name.

CircleCI: Create Schedule

circleci_create_schedule

Create a scheduled pipeline. From then on CircleCI starts real runs on the timetable, which draws on the organization's plan usage on every tick, so keep the timetable as sparse as the job needs. Available only on GitHub OAuth and Bitbucket Cloud organizations. Deleting the schedule stops it.

CircleCI: Create Webhook

circleci_create_webhook

Register an outbound webhook on a project. CircleCI then POSTs to the URL whenever the chosen events fire (workflow-completed, job-completed), signing each request with the signing secret so the receiver can verify it. Creating one changes no existing behaviour and Delete Webhook removes it. Turning off TLS verification means CircleCI stops checking the receiver's certificate.

CircleCI: Delete Checkout Key

circleci_delete_checkout_key

DESTRUCTIVE: delete a checkout key. If it is the key the project clones with, every following build fails at the checkout step until a new key is created and registered with the VCS. The private half is gone and cannot be restored; recovery means creating a new key, not undoing this.

CircleCI: Delete Context

circleci_delete_context

DESTRUCTIVE: delete a context. CircleCI documents that this also deletes EVERY environment variable inside it, and those values are unrecoverable because the API only ever returns variable names. Any job whose config names this context fails on its next run.

CircleCI: Delete Context Env Var

circleci_delete_context_env_var

DESTRUCTIVE: remove an environment variable from a context. The value is unrecoverable, because the API never returns context variable values and nothing can copy it first. Every job that uses this context loses the variable on its next run.

CircleCI: Delete Env Var

circleci_delete_env_var

DESTRUCTIVE: permanently delete a project environment variable. The value is unrecoverable, because CircleCI only ever returns it masked and no automation can take a copy first. Jobs that read the name start failing on their next run. Recreating it means having the original secret to hand.

CircleCI: Delete Schedule

circleci_delete_schedule

DESTRUCTIVE: delete a scheduled pipeline. The trigger stops immediately and its timetable, parameters and attribution are gone; recreating it means re-entering all of them. Runs the schedule already started are not affected.

CircleCI: Delete Webhook

circleci_delete_webhook

DESTRUCTIVE: delete an outbound webhook. Deliveries stop at once and the signing secret is gone, so recreating the webhook means issuing a new secret and updating the receiver. Anything downstream that depended on these deliveries goes quiet without erroring.

CircleCI: Rerun Workflow

circleci_rerun_workflow

Rerun a workflow and get the new workflow id back. This STARTS A REAL CI RUN: it queues compute that draws on the organization's CircleCI plan usage and re-executes the workflow's jobs, including any deploy jobs, so rerunning a release workflow deploys again. The original workflow is untouched and the new run can be stopped with Cancel Workflow. Set from failed to restart from the failed job onward, or pass specific job ids to rerun just those.

CircleCI: Set Context Env Var

circleci_set_context_env_var

Add an environment variable to a context, or replace the value of one that already exists under that name. The response carries the variable name and timestamps only. Replacing overwrites a value that cannot be read back first, so check List Context Env Vars before reusing a name.

CircleCI: Trigger Pipeline

circleci_trigger_pipeline

Start a new pipeline on a branch or tag, optionally passing pipeline parameters. This RUNS REAL CI: it queues compute that draws on the organization's CircleCI plan usage and it executes whatever the config says, which can include deploy jobs that change live environments. Nothing is destroyed and a run in flight can be stopped with Cancel Workflow or Cancel Job. Branch and tag are mutually exclusive. CircleCI marks this endpoint superseded: it does not work for GitLab or GitHub App projects, which use Trigger Pipeline Run.

CircleCI: Trigger Pipeline Run

circleci_trigger_pipeline_run

Start a pipeline from a named pipeline definition. This is the trigger CircleCI recommends and the only one that works for GitHub App, GitHub Enterprise Server and Bitbucket Data Center projects. It RUNS REAL CI: it queues compute that draws on the organization's plan usage and can run deploy jobs against live environments; a run in flight can be stopped with Cancel Workflow. The three path segments are the project slug split at its slashes, exactly as shown in Project Settings > Overview. Config branch or tag chooses where the config file is read from; checkout branch or tag chooses what the checkout step clones.

CircleCI: Update Schedule

circleci_update_schedule

Update a scheduled pipeline. Only the fields you fill are sent, and a sent field REPLACES its whole value: a new timetable object replaces the old timetable outright, and a new parameters object replaces the old parameters, so include every key you still want. Fetch the schedule first if you are changing one key of either.

CircleCI: Update Webhook

circleci_update_webhook

Update an outbound webhook. Only the fields you fill are sent; the events array REPLACES the existing list, so include every event you still want. Changing the signing secret invalidates signatures the receiver already trusts, so update the receiver at the same time. The scope cannot be changed.

Using the integration

On the automation canvas

CircleCI nodes chain with every other node: a scheduled sweep can read CircleCI: Get Workflow Metrics and write success rate and duration percentiles into a Mattering database, a failed build can open a Mattering Productivity task with the failing test names attached, and a release checklist can call CircleCI: Trigger Pipeline Run only after a person marks the checklist done. Two values are the backbone of almost every chain: the project slug you copy once, and the pipeline id from CircleCI: List Project Pipelines, which leads to workflows through CircleCI: List Pipeline Workflows and then to jobs through CircleCI: List Workflow Jobs.

From AI assistants over MCP

Every node speaks MCP, the open protocol for connecting AI assistants to tools, so Claude, ChatGPT, and any other MCP-capable assistant can drive the same surface, alongside Matter, the assistant built into the platform. The read nodes are the safest surface to hand an agent: an agent that can call CircleCI: List Workflow Jobs, CircleCI: Get Job Details and CircleCI: Get Job Test Metadata can explain a broken build in one turn. Keep the six destructive nodes and the three run-starting nodes behind conditions or approval steps rather than exposing them as bare agent tools.

Choosing the right trigger node

Both CircleCI trigger endpoints ship, because which one works depends on how your organization connects to its version control provider. CircleCI: Trigger Pipeline takes a project slug plus a branch or tag (they are mutually exclusive) and optional pipeline parameters; CircleCI marks that endpoint superseded and it does not work for GitLab or GitHub App projects. CircleCI: Trigger Pipeline Run is the recommended one and the only one that works for GitHub App, GitHub Enterprise Server and Bitbucket Data Center projects. It takes the project slug split into its three path segments, a pipeline definition id from CircleCI: List Pipeline Definitions, and it separates where the config is read from (config branch or tag) from what the checkout step clones (checkout branch or tag). Both start real runs against the organization's plan usage.

Watching a run to completion

There is no polling built into a node, so a workflow does the waiting explicitly, and that is usually two steps. Start the run, then loop on CircleCI: Get Workflow and read its status field, which is what tells you whether the run is still going, succeeded, failed, or is sitting on_hold at an approval job. When it settles, CircleCI: List Workflow Jobs gives the per-job outcome and CircleCI: Get Job Details the run times and resource class. Keep the loop interval generous: CircleCI states that frequent polling is a way to get throttled, and a 429 in the middle of a wait loop is a self-inflicted failure.

Secrets, contexts and checkout keys

CircleCI never hands back a secret, and the nodes inherit that. CircleCI: List Env Vars and CircleCI: Get Env Var return project values masked as four x characters plus the last four, and CircleCI: List Context Env Vars returns context variable names with no value at all, which makes both safe reads for an audit sweep. Writes are where care is needed: CircleCI: Create Env Var and CircleCI: Set Context Env Var both state on the node that reusing an existing name overwrites its value rather than failing, replacing a value nobody can read back first, so check the listing before reusing a name. CircleCI: List Checkout Keys returns public material only, with each key's type, fingerprint and age, which is exactly the input a rotation review needs; prefer a deploy key over a user key, since a user key acts as the authorizing person across every repository they can read.

Insights reporting, and the credit caveat

The Insights nodes cover four grains: CircleCI: Get Org Summary Metrics for the organization, CircleCI: Get Project Summary Metrics for every workflow and branch in a project, CircleCI: Get Workflow Metrics and CircleCI: Get Workflow Summary for workflows, and CircleCI: Get Workflow Job Metrics plus CircleCI: Get Job Timeseries for the jobs inside one. Their honest limits are on the nodes: summary metrics refresh daily so the last 24 hours may be missing, aggregation reaches back at most 90 days, that same retention window bounds how far back a timeseries request can reach, and hourly buckets are retained for 48 hours against 90 days for daily ones. One piece of our own guidance sits on top of those: because success rate and duration percentiles are rates rather than counts, combine them by refetching the window you actually want instead of averaging buckets you already have. The caveat CircleCI publishes on these endpoints applies to any page or dashboard you build from them: Insights is not a financial reporting tool, its credit figures do not share a source of truth with the billing pages, and differences from the Plan Overview page are expected.

Schedules and webhooks as managed configuration

CircleCI: List Schedules, CircleCI: Create Schedule and CircleCI: Update Schedule make scheduled pipelines something a workflow can reconcile rather than something that drifts in the UI, and CircleCI: List Webhooks, CircleCI: Create Webhook and CircleCI: Update Webhook do the same for outbound webhooks, which CircleCI fires on workflow-completed and job-completed and signs with the secret you set, in a circleci-signature header carrying an HMAC-SHA256 digest of the body. Point one at an inbound webhook trigger in Mattering and a finished workflow can start an automation; verify that signature in the receiver before acting on a payload. Two behaviours to plan for: the update nodes state that a field they send replaces its whole value, so a new timetable or a new events array replaces the old one outright, and CircleCI documents the schedule endpoints as covering GitHub OAuth and Bitbucket Cloud pipeline definitions, with GitHub App schedules living under pipeline definition triggers instead.

The six destructive nodes, gated

All six are final, and two are final in the strongest sense. CircleCI: Delete Env Var and CircleCI: Delete Context Env Var destroy values that no automation could have copied first, because the API returns project values masked and context values not at all, so recreating one means having the original secret to hand. CircleCI: Delete Context takes every variable inside the context with it, and any job whose config names that context fails on its next run. CircleCI: Delete Checkout Key can break cloning outright: if it is the key the project clones with, every following build fails at the checkout step until a new key is created and registered with the version control provider. CircleCI: Delete Schedule loses the timetable, parameters and attribution, and CircleCI: Delete Webhook stops deliveries and discards the signing secret, so downstream automations go quiet without erroring. The pattern for all six is the same: read or recreate first, and put the delete behind a condition, an approval task, or a manual run rather than a bare trigger.

What stays off the canvas

Some CircleCI endpoints are deliberately absent. Workflow approval gates are not here, because approving your own gate from an automation removes the point of the gate. Creating and deleting organizations and projects are not here either: project deletion in particular is a one-call loss of history that does not belong next to a pipeline listing. Policy management, OIDC custom claims, context restrictions and the URL orb allow list are org security surfaces driven by uploaded bundles rather than canvas fields; usage export jobs and group administration produce signed files rather than node output; deploy environments, components, versions and rollback are a separate deploy-markers product; and the OpenTelemetry exporter surface is left out as well. Pipeline continuation is also out, since it belongs inside a running setup job rather than on a canvas.

Troubleshooting

Test Connection fails with a 401 and a message about logging in first
That is CircleCI's own response to a request with no valid personal token, so a failure here is about the credential. Check for leading or trailing whitespace from the copy, and confirm the token was not revoked in User Settings, then Personal API Tokens after you saved it. The most common cause is the wrong kind of credential: project API tokens are not supported on API v2 and always fail here, even though they are real CircleCI tokens. Create a personal API token instead, copy it at creation, and update the credential in Connectors.
A project-scoped node returns a 404 or reports the project was not found
Almost always the project slug. CircleCI documents two forms and tells you to treat the value as an opaque string: GitHub OAuth and Bitbucket Cloud organizations use the readable version control slug, organization and repository form such as gh/example-org/example-repo, while GitHub App, GitLab and Bitbucket Data Center organizations use an opaque form built from two identifiers under a circleci prefix. Composing the readable form by hand for an organization that uses the opaque one produces exactly this error. Copy the slug from Project Settings, then Overview, rather than assembling it. If the slug is right, the other cause is reach: a personal API token only sees projects its owner can see.
Trigger Pipeline fails on a GitLab or GitHub App project
That endpoint does not support those project types. CircleCI marks the project-slug pipeline trigger superseded and documents that it does not work for GitLab or GitHub App projects. On a GitHub App project, use CircleCI: Trigger Pipeline Run instead: run CircleCI: Get Project for the project id, run CircleCI: List Pipeline Definitions for the definition id, and give the trigger node the three path segments of the project slug plus that definition id. It also splits config source from checkout target, so set the config branch or tag for where the config file is read from and the checkout branch or tag for what the checkout step clones. On a GitLab project there is no second option to fall back to. CircleCI documents the newer endpoint as supporting every organization and pipeline type except GitLab, so neither trigger node applies there and those pipelines have to be started from CircleCI itself.
The schedule nodes return nothing for a project that clearly has schedules
Check how the organization connects to its version control provider. CircleCI documents the schedule endpoints as covering schedules on GitHub OAuth and Bitbucket Cloud pipeline definitions; on GitHub App organizations, scheduled runs live under pipeline definition triggers instead, which is a different surface. An empty list from CircleCI: List Schedules on a GitHub App project is therefore the API answering honestly rather than a permission problem. The same distinction explains a 404 from CircleCI: Get Schedule for an id copied out of the web app on those organizations.
A list node returns only part of the data
CircleCI paginates with an opaque token and nothing else: collection reads return an items array with a next_page_token, and the next page is fetched by passing that value back as the page token on the same node. There is no page number and no page size parameter anywhere in API v2, so a node cannot offer one. In a workflow, read data.next_page_token, and if it is not null, loop the node with that value until it comes back empty. One list has a documented cap worth knowing: CircleCI: List Insights Branches returns at most 5,000 branches.
Nodes start failing with HTTP 429
The requests are being throttled. CircleCI returns 429 for throttled requests, usually with a Retry-After header, and the current allowance is readable from the response through the RateLimit-Limit, RateLimit-Remaining and RateLimit-Reset headers and the X-RateLimit-Limit-Second, Minute, Hour and Day family. CircleCI publishes no request-per-minute figures, states that limits differ across parts of the API and are subject to change, and names frequent polling as a way to get throttled. The practical fixes are the obvious ones: widen the interval on any wait loop, run Insights sweeps on a schedule rather than on every event, and let the node's error output drive a wait step instead of retrying immediately.
Get Job Artifacts or Get Job Test Metadata returns an empty list
Both read what a job uploaded, so an empty result usually means the job uploaded nothing. Artifacts appear only for jobs with a store_artifacts step, and test records appear only for jobs with a store_test_results step, and only in the formats CircleCI parses. Confirm the job number is the one that ran the tests rather than a neighbouring job in the workflow: CircleCI: List Workflow Jobs gives the right job number, and approval jobs have none at all because they gate rather than run. When artifacts do come back, the URLs are download links to fetch with a following HTTP node using the same CircleCI token.
Insights numbers do not match the CircleCI billing page
Expected, and CircleCI says so on the endpoints themselves: Insights is not a financial reporting tool, its credit figures do not share a source of truth with the billing pages, and discrepancies with the Plan Overview page are normal. Treat credits from CircleCI: Get Workflow Metrics or CircleCI: Get Job Timeseries as an indicative engineering signal, not an invoice line. Two related surprises come from refresh and retention rather than accounting: summary metrics refresh daily, so today's runs may be missing, and hourly timeseries buckets are retained for 48 hours while daily buckets go back 90 days.
Environment variable reads only show xxxx values
That is the masking CircleCI applies, not a truncated response. Project variable reads return four x characters plus the last four characters of the real value, which is exactly what the web app shows, and context variable reads return no value at all. There is no node, and no CircleCI endpoint, that reads a stored secret back out. Use the listings to answer which names exist and when they changed, keep the authoritative values in a secret store, and remember the consequence for deletes: because nothing can copy a value first, CircleCI: Delete Env Var and CircleCI: Delete Context Env Var are unrecoverable in the strongest sense.
An update wiped fields I did not send
The schedule and webhook update nodes state that a field they send replaces its whole value. CircleCI: Update Schedule sends a new timetable object in place of the old timetable outright, and a new parameters object in place of the old parameters, so include every key you still want; fetch the current state with CircleCI: Get Schedule first when you are changing one key. CircleCI: Update Webhook behaves the same way with its events array. One extra consequence on webhooks: changing the signing secret invalidates signatures the receiver already trusts, so update the receiver in the same change. The webhook update request also carries no scope field, only name, events, url, verify-tls and signing-secret, so an existing webhook cannot be repointed at a different project.

CircleCI is a trademark of its respective owner. Mattering uses platform names to identify the services these integrations connect to; no endorsement or affiliation is implied.

Start Free Explore our Products