# Cancel a Run

Request cancellation, then retrieve the same Run to learn its final execution and billing outcome.

## Endpoint

This request has no JSON body. The credential must have permission for the tool's behavior. Inspection reports supplier cancellation support.

A 200 or 202 response reports the current Run; it does not prove the supplier stopped. Continue retrieving the original Run until execution and billing are resolved.

```
POST /v1/runs/{runId}/cancel
```

## Parameters

| Name | Location | Type | Required | Constraints |
| --- | --- | --- | --- | --- |
| runId | path | string | Required | — |

## Request example

Set PURRKEY_API_KEY in your trusted server or terminal environment. Replace any angle-bracket placeholders with values from your own inspection or Run.

```
curl --fail-with-body --request POST 'https://api.purrkey.app/v1/runs/<runId>/cancel' \
  -H "Authorization: Bearer $PURRKEY_API_KEY"
```

## Successful response

Success HTTP status: 200, 202. Top-level response fields are listed below. Conditional and nested requirements are defined in the downloadable OpenAPI contract.

| Field | Type | Required | Constraints |
| --- | --- | --- | --- |
| runId | string | Required | — |
| toolId | string | Required | — |
| toolRevision | string | Required | — |
| toolName | string | Optional / conditional | — |
| status | string | Required | QUEUED \| SUBMITTING \| RUNNING \| WAITING_PROVIDER \| SUCCEEDED \| FAILED \| CANCELED \| TIMED_OUT \| UNKNOWN |
| billing | object | Required | — |
| createdAt | string | Required | date-time |
| updatedAt | string | Required | date-time |
| cancelRequestedAt | string | Optional / conditional | date-time |
| payment | object | Optional / conditional | — |
| input | JSON value | Optional / conditional | — |
| result | object | Required | — |
| error | object | Optional / conditional | — |
| pollAfterMs | integer | Optional / conditional | int32; Minimum: 0 |

## Errors and related reading

- [Error handling](/docs/guides/errors): Read requestId, business codes and safe retry behavior.
- [Download OpenAPI](/docs/openapi.yaml): The complete HTTP contract, version 0.4.3.