# Runs, retries and cancellation

Recover interrupted calls using the original request identity, without buying the same task twice.

## Save the request before submitting

An idempotency key identifies one intended task within an account workspace. It is separate from the API key used for authentication. API keys and clients belonging to the same workspace share this request identity. The same idempotency key and effective request recover the original Run without another execution or charge. Changing the input, revisions or spending terms under the same key produces a conflict.

Generate a new idempotency key only for a new task. Persist the complete request before sending it, so a process restart or lost response does not erase the identity needed for recovery.

## Keep polling the original Run

Submission may return HTTP 202. Retrieval returns HTTP 200 with the current state, including pending states. Follow pollAfterMs when present and use bounded waits.

A client timeout ends the local wait, not the supplier's work. UNKNOWN means the outcome is being checked. Keep the same Run ID; do not automatically resubmit a new task.

```
purrkey get-run --id '<runId>' --wait 30s --output result.json
```

## Recover a lost submission response

Reuse the unchanged request file and the same account. The CLI journals the request before sending it and stores the Run ID when known. Repeating this command recovers the saved operation. The local journal is specific to the API origin and API key. After rotating credentials, use get-run with the original Run ID and an authorized key for the same account. If the ID is unknown, resend the unchanged request with its original idempotency key. If a Run ID was returned but journal saving failed, use get-run with that ID.

```
purrkey run --request request.json --wait 30s --output result.json
```

## Request cancellation

Cancellation is a request, not confirmation that a supplier stopped or that the call was refunded. Retrieve the same Run afterward and check execution and billing. For TinyFish browser automation, the final bill includes confirmed steps already executed, even if the supplier reports failure or cancellation.

```
purrkey cancel-run --id '<runId>'
```