Overview
Sometimes a workflow or job gets stuck in a stale or stalled state in the CircleCI web app. The UI may show the workflow as still running, or it may not offer a Rerun option. When that happens, you can still rerun the workflow through the CircleCI API. The API doesn't need the UI to show the workflow as completed first.
Before you begin
You need the workflow ID. It's the UUID in the workflow URL:
https://app.circleci.com/pipelines/<vcs>/<org>/<repo>/<pipeline-number>/workflows/<WORKFLOW_ID>You need a CircleCI personal API token.
Option 1: Rerun with the v3 API
Send a POST request to the v3 rerun endpoint:
POST /api/v3/workflows/{id}/rerun
See the v3 API reference for the full request details.
Option 2: Rerun with the v2 API
If the v3 API doesn't work for you, use the v2 rerunWorkflow endpoint:
curl --request POST \
--header "Circle-Token: ${CIRCLE_TOKEN}" \
--header "Content-Type: application/json" \
--data '{"enable_ssh": false, "from_failed": false}'
A successful request returns HTTP 202 and the ID of the new workflow:
{ "workflow_id": "0e53027b-521a-4c40-9042-47e72b3c63a3" }
Request body options
Parameter | Description |
| Set to |
| A list of job IDs to rerun. Can't be combined with |
| Enables SSH for the rerun job. Requires |
Tip: In a multi-line curl command, put a backslash (\) at the end of every line except the last. A missing backslash means the request body is dropped, and the whole workflow reruns from the start.
If you see "Workflow must be in a terminal state to be rerun"
If either endpoint returns a message like this:
Workflow must be in a terminal state to be rerun
the API sees the workflow as still in progress.
If the workflow is genuinely running or on hold, see Error: 'Workflow must be in a terminal state to be rerun' When Using the Rerun API.
If the workflow is stalled and you're sure nothing is actually running, contact CircleCI Support. Include a link to the workflow or build you're trying to rerun. The workflow may have been missed by our engineering team's cleanup of stalled builds, and we'll investigate.