# Cancelling Runs
Runs that are currently in progress can be cancelled using the dashboard controls or via an API call.
Cancelling a run can be useful for:
* preventing a run from timing out
* optimizing usage of your CI provider resources
* reducing the number of recorded tests
{% hint style="warning" %}
**Please note:** Cancelling a run cannot be undone
{% endhint %}
## Cancelling Runs via Dashboard
In-progress runs can be cancelled by clicking the "Cancel Run" button in the Runs Feed view. You can also cancel a run when from the Run Details view.
Cancelling a Run via Dashboard
The canceled run will be tagged accordingly, and the dashboard will display the user, date, and time of cancellation.
Example of a run cancelled by a dashboard user
## Cancelling Runs via API
You can programmatically cancel a run via the `PUT runs/:runId/cancel` HTTP API call. For example, here is an example of `curl` command that cancels a particular run
```bash
curl --location --request PUT 'https://api.currents.dev/v1/runs/:runId/cancel' \
--header 'Authorization: Bearer '
```
By using the API call you can extend the - for example:
* cancel a run after CI pipeline is stopped/cancelled
* cancel a run when a particular condition is met, e.g.:
* activate [HTTP Webhooks](/resources/integrations/http-webhooks.md) and parse the results
* based on the results (e.g. encountering a particular error message), send the cancellation request
* cancel a run when a certain number of failed tests are detected (it is natively supported via [Failing Fast](/guides/ci-optimization/fail-fast-strategy.md))
### Cancellation by Fail-Fast
If you have [Failing Fast](/guides/ci-optimization/fail-fast-strategy.md) activated for a project, runs cancelled because of fail-fast strategy will be marked with a special badge:
Example of a run cancelled by fail-fast strategy
## GitHub Actions Workflow Cancellation
You can automatically cancel Currents runs (cypress and playwright) when cancelling GitHub Actions workflow using [cancel-run-gh-action](https://github.com/currents-dev/cancel-run-gh-action).
Check out the [example workflow configuration](https://github.com/currents-dev/currents-examples/blob/main/cypress/github-actions/.github/workflows/currents.yml):
```yaml
# Run all Currents tests
- name: Run Cypress on Currents.dev
uses: cypress-io/github-action@v4
with:
command: npx cypress-cloud run --record --parallel --browser chrome --key ${{ secrets.CURRENTS_RECORD_KEY }} --ci-build-id ${{ github.repository }}-${{ github.run_id }}-${{ github.run_attempt}}
- name: Cancel the run if the workflow is cancelled
if: ${{ cancelled() }}
uses: currents-dev/cancel-run-gh-action@v1
with:
api-token: ${{ secrets.CURRENTS_API_KEY }}
github-run-id: ${{ github.run_id }}
github-run-attempt: ${{ github.run_attempt }}
```
The example above uses a [GitHub Actions repository secret](https://docs.github.com/en/actions/security-guides/encrypted-secrets#creating-encrypted-secrets-for-a-repository) named `CURRENTS_API_KEY.` For creating a new API secret please refer to [Authentication](/api/get-started/authentication.md).
After the step is enabled, cancelling a GitHub Actions workflow will trigger cancellation:
Example of a cancellation step
The associated Currents run will be cancelled with the corresponding notes:
#### Cancelling with CI Build ID
The current implementation allows to cancel a run with CI information that is usually available in the Github environment variables.
But sometimes is required to explicitly define what run needs to be cancelled, so this functionality allows cancelling a run with a known CI Build ID (see [CI Build ID](/guides/parallelization-guide/ci-build-id.md)) and a project ID (see [Projects](/dashboard/projects.md)) which are usually known beforehand in a CI environment as these are required parameters for executing a run.
```yaml
# Run all Currents tests
- name: Run Cypress on Currents.dev
uses: cypress-io/github-action@v4
env:
CURRENTS_CI_BUILD_ID: "a-custom-ci-build-id"
CURRENTS_PROJECT_ID: "my-project-id"
with:
command: npx pwc --key ${{ secrets.CURRENTS_RECORD_KEY }} --project-id ${{ CURRENTS_PROJECT_ID }} --ci-build-id ${{ CURRENTS_CI_BUILD_ID }}
- name: Cancel the run if the workflow is cancelled
if: ${{ cancelled() }}
uses: currents-dev/cancel-run-gh-action@v1
with:
api-token: ${{ secrets.CURRENTS_API_KEY }}
github-run-id: ${{ github.run_id }}
github-run-attempt: ${{ github.run_attempt }}
ci-build-id: ${{ env.CURRENTS_CI_BUILD_ID }}
project-id: ${{ env.CURRENTS_PROJECT_ID }}
```
The example above uses `CURRENTS_CI_BUILD_ID` and `CURRENTS_PROJECT_ID` as beforehand known variables to pass it down to the run cancellation workflow.
{% hint style="info" %}
`api-token`, `github-run-id` and `github-run-attempt` are still required parameters that must be passed to the cancellation workflow.
{% endhint %}
## FAQ
### What happens when a run is cancelled?
Cancelling a run affects in-progress and pending tests, as well as integrations and run analytics.
* the run will be marked as "Cancelled", depending on the test's status, it can also become "Failed" or "Passed". See [Test Status](/dashboard/tests/test-status.md).
* in-progress tests will run to completion, the dashboard will accept their result
* attempts to start a new test for a cancelled run would fail with the error message `Run is cancelled`
### Cancelling runs and analytics
* Cancelled runs are excluded from Runs Duration Insights
* Cancelled runs are excluded from Test / Spec Size Insights
* Tests recorded as part of a cancelled run are still included in Tests Insights charts
### How does cancelling a run affect test records plan usage?
* Only fully recorded tests consume your organization's test records limit.
* Cancelled runs do consume your organization's runs limit (for organizations on deprecated runs-based plans)
### How does cancelling a run affect integrations (GitHub, Slack, etc.)?
#### GitHub / BitBucket Commit Status Check
* Commit status checks will display `Cancelled by ` message
* Commit status check outcome will be set according to the last known run status, for example
* if no failed tests were recorded before the cancellation, the status check outcome will be a `success`
* otherwise, the status check outcome will be a `failure`
#### GitHub PR Comment
* Currents will post a new PR comment with `Cancelled by ` message
* PR comment details will be set according to the last known run status
#### Slack / MS Teams
* Currents will post a cancellation notification with the last known run results
#### HTTP Webhooks
A new HTTP `POST` request will be emitted with the last known run results and event type `RUN_CANCELED` See [HTTP Webhooks](/resources/integrations/http-webhooks.md) for details.
---
# Agent Instructions: Querying This Documentation
If you need additional information that is not directly available in this page, you can query the documentation dynamically by asking a question.
Perform an HTTP GET request on the current page URL with the `ask` query parameter:
```
GET https://docs.currents.dev/dashboard/runs/cancel-run.md?ask=
```
The question should be specific, self-contained, and written in natural language.
The response will contain a direct answer to the question and relevant excerpts and sources from the documentation.
Use this mechanism when the answer is not explicitly present in the current page, you need clarification or additional context, or you want to retrieve related documentation sections.