# Cancel a run

> operationId: `cancelRun`


## Request

Cancels a run. The request body is {}. No If-Match or catalog revision is needed. If the run is already in a terminal state, the current state is returned, and success is not changed to cancelled. cancel_requested is not the same as cancelled. A quarantined environment can't be force-released so that the run can be started again.

- **Prerequisites**: Cancel only runs that the current account/team started and that you are still authorized to access.
- **Authentication**: Same as the rest of the Local API; see [Authentication](/api-reference/getting-started/authentication). Resources belong to the current account/team data scope.
- **Side effects**: Registers the cancellation intent and starts supervising the stop. Website actions that already happened are not undone.
- **Completion signal**: 202 means the cancellation request was registered. Only later stop evidence and the isolation state can show whether the browser can be reused.
- **Retries**: Recover the same intent with the original key, the original body (if any), and the original If-Match (if this endpoint requires one). On an HTTP timeout, first [get the request receipt](/browser-rpa/api/get-request-receipt). Don't generate a new key.


### Endpoint

```http
POST /api/rpa/browser/v1/runs/{runId}/cancel
```

Local API: `http://127.0.0.1:<port>/api/rpa/browser/v1/runs/{runId}/cancel`. Use the port configured in the client.

### Headers

| Parameter | Type | Required | Description and constraints |
|  --- | --- | --- | --- |
| `Authorization` | string | When Local API authentication is enabled | See [Authentication](/api-reference/getting-started/authentication). |
| `Idempotency-Key` | string | No | Recommended. Generate a UUID for each new write intent and keep it when you retry after a disconnect; the same key never runs twice. Without it there is no duplicate protection, so a retry after a timeout can run the write again. When present, it must be a UUID. Format "uuid". |


Content type: `Content-Type: application/json` (required).

### Path parameters

| Parameter | Type | Required | Description and constraints |
|  --- | --- | --- | --- |
| `runId` | string | Yes | ID of the run. Min length 1; max length 128. |


### Query parameters

None.

### Request body

Type: object.

### Request example

This is a documentation example; it was not sent to a live client. Set `RPA_BASE_URL` as described in [API conventions](/browser-rpa/api/common). Resource variables, the catalog revision, and ETags come from actual responses.

Save the complete JSON below as `cancel-run.request.json`. Replace every value whose identifier contains `example` with a value from an actual response. The node IDs in the creation sample are workflow-local IDs and can stay as they are.

```json
{}
```

```bash
curl -i -X POST "${RPA_BASE_URL}/runs/${RPA_RUN_ID}/cancel" \
  -H 'Content-Type: application/json' \
  -H "Idempotency-Key: ${RPA_REQUEST_KEY}" \
  --data-binary @cancel-run.request.json
```

## Response

### 202

202 means the cancellation request was registered. Only later stop evidence and the isolation state can show whether the browser can be reused.

Body: `application/json`. The top-level `data` uses the model below. For `meta`, see [Metadata](/browser-rpa/api/data-types#metadata).

| Field | Type | Required | Description and constraints |
|  --- | --- | --- | --- |
| `id` | string | Yes | Unique ID of the resource or node. Take it from a previous response; don't guess it. Min length 1; max length 128. |
| `status` | [RunStatus](/browser-rpa/api/data-types#runstatus) | Yes | Current status. Evaluate it against the enum values of the model. |
| `template` | object | Yes | The complete body of a candidate template, or the template summary frozen for the run. Read it according to the model that contains it. |
| `environment` | object | Yes | Summary of the target environment frozen for the run. |
| `createdAt` | integer | Yes | Creation time, Unix milliseconds. Minimum 0. |
| `startedAt` | integer or null | Yes | Start time. null until the run starts (always present in node records). |
| `endedAt` | integer or null | Yes | End time. null until the run ends. |
| `startAfter` | integer or null | Yes | Earliest start time, in Unix milliseconds, when the template task has a delayed start. Until then, the run stays queued and doesn't occupy the environment. null when there is no delay, or for a debug run. |
| `hasNodeErrors` | boolean | Yes | Whether any node error occurred. Don't look only at the overall status and ignore this field. |
| `isolation` | object or null | Yes | Environment isolation state, or null. A quarantined environment can't be reused. |


**`template` fields**

| Field | Type | Required | Description and constraints |
|  --- | --- | --- | --- |
| `template.id` | string | Yes | Unique ID of the resource or node. Take it from a previous response; don't guess it. Min length 1; max length 128. |
| `template.title` | string | Yes | Display name. On template writes, 1–100 characters after trimming. |
| `template.version` | integer | Yes | Current editable template version. Read it from an actual response. Minimum 1. |
| `template.revisionId` | string | Yes | Immutable revision ID. Min length 1; max length 128. |


**`environment` fields**

| Field | Type | Required | Description and constraints |
|  --- | --- | --- | --- |
| `environment.id` | string | Yes | Unique ID of the resource or node. Take it from a previous response; don't guess it. Min length 1; max length 128. |
| `environment.name` | string | Yes | Public name. |


**`isolation` fields**

| Field | Type | Required | Description and constraints |
|  --- | --- | --- | --- |
| `isolation.state` | `quarantined` / `released` | Yes | Environment isolation state: quarantined or released. |
| `isolation.reason` | string | Yes | Reason for the unavailability, the isolation, or the runtime check. |
| `isolation.since` | integer | Yes | Time the isolation started, Unix milliseconds. Minimum 0. |
| `isolation.releasedAt` | integer or null | Yes | Release time. null if the environment hasn't been released yet. |


### Response example

All IDs, timestamps, hashes, and run results are sample data. They don't indicate that the sample was executed.

```json
{
  "data": {
    "id": "run_example",
    "status": "cancel_requested",
    "template": {
      "id": "template_example",
      "title": "Read the page URL",
      "version": 1,
      "revisionId": "revision_example_1"
    },
    "environment": {
      "id": "environment_example",
      "name": "Example browser profile"
    },
    "createdAt": 1793318400000,
    "startedAt": null,
    "endedAt": null,
    "startAfter": null,
    "hasNodeErrors": false,
    "isolation": null
  },
  "meta": {
    "requestId": "7d498f20-7bab-4e59-9b05-88daf51230e9",
    "catalogRevision": "sha256:aaaaaaaaaaaaaaaaaaaaaaaaaaaaaaaaaaaaaaaaaaaaaaaaaaaaaaaaaaaaaaaa"
  }
}
```

### Error responses

| HTTP | error.code | What to do |
|  --- | --- | --- |
| 409 | RPA_REQUEST_CONFLICT | The method/path/body/If-Match sent with the same key differs from the original intent. |
| 504 | RPA_REQUEST_TIMEOUT | This only means that the HTTP wait timed out. Check the original request receipt first. |


A same-key write replay keeps the ETag of the original response (if there was one; it may be out of date). The receipt contains only data, without response headers. To continue editing, send a new GET first; see [API conventions](/browser-rpa/api/common).

For common 400/401/403/404/429/5xx errors and failure fields, see [Errors and recovery](/browser-rpa/api/common#errors-and-recovery). Error response example (403):

```json
{
  "error": {
    "code": "RPA_PERMISSION_DENIED",
    "message": "The request Host or Origin is not allowed, or the current identity can't access the target environment",
    "retryable": false,
    "issues": [],
    "details": null
  },
  "meta": {
    "requestId": "7d498f20-7bab-4e59-9b05-88daf51230e9",
    "catalogRevision": "sha256:aaaaaaaaaaaaaaaaaaaaaaaaaaaaaaaaaaaaaaaaaaaaaaaaaaaaaaaaaaaaaaaa"
  }
}
```

## Related

[Local API reference](/browser-rpa/local-api) · [API conventions](/browser-rpa/api/common) · [Data models](/browser-rpa/api/data-types) · [Workflow structure](/browser-rpa/api/workflow) · [Quickstart](/browser-rpa/quickstart)

Both the 202 response and a same-key replay include `Location: /api/rpa/browser/v1/runs/<runId>`. Use it to read the current state.