# Cancel, pause, resume, or stop the current turn

`PATCH /o/{org}/p/{project}/sessions/{session}`

One status change per request. `cancelled` ends the run. `paused` parks
a resumable sandbox with its disk and memory; `running` wakes it. Both
answer `202` with an `operation_id`. `stop_turn` interrupts the turn in
progress and keeps the session. Any other field, or another `status`, is
`400`.

## Parameters

| Name | In | Type | Required | Description |
| --- | --- | --- | --- | --- |
| `org` | path | string | yes | The org's slug or id. A caller with no role in the org gets `404`. |
| `project` | path | string | yes | A Project's handle (name) or id, resolved inside `{org}` — OR the reserved sentinel `_` meaning "no Project" (a direct-repo / repo-less dispatch on `POST`; "no Project constraint, resolve by session id alone" everywhere else). A real handle that doesn't match the session's actual Project is `404`.  |
| `session` | path | string | yes | The session's full id (`execution_id`). |

## Request body

- `status` (string, required, one of `cancelled`, `paused`, `running`, `stop_turn`)

## Example: example

```bash
curl -X PATCH "https://api.prix.dev/o/$RUSH_ORG/p/_/sessions/$SESSION_ID" \
  -H "Authorization: Bearer $RUSH_API_KEY" \
  -H "Content-Type: application/json" \
  -d '{
    "status": "cancelled"
  }'
```

```typescript
const org = process.env.RUSH_ORG;
const sessionId = process.env.SESSION_ID;

const res = await fetch(`https://api.prix.dev/o/${org}/p/_/sessions/${sessionId}`, {
  method: "PATCH",
  headers: {
    Authorization: `Bearer ${process.env.RUSH_API_KEY}`,
    "Content-Type": "application/json",
  },
  body: JSON.stringify({
    status: "cancelled",
  }),
});

console.log(res.status, await res.json());
```

```python
import os

import requests

org = os.environ["RUSH_ORG"]
session_id = os.environ["SESSION_ID"]

res = requests.patch(
    f"https://api.prix.dev/o/{org}/p/_/sessions/{session_id}",
    headers={"Authorization": f"Bearer {os.environ['RUSH_API_KEY']}"},
    json={
        "status": "cancelled",
    },
)

print(res.status_code, res.json())
```

## Responses

### 200

The change took effect.

- `ok` (boolean, required)
- `status` (string, required, one of `cancelled`, `stop_turn_confirmed`)

### 202

A pause or resume was accepted and runs in the background.

- `operation_id` (string, required)

### 400

Malformed request.

### 401

No bearer, an unknown, revoked or expired one, or an API key on a route keys cannot call.

### 404

No such resource for the caller, including one that exists in an org the caller cannot see.

### 409

The session cannot make this change now: it already finished, has no
sandbox to pause or resume, has no turn to stop (`NO_ACTIVE_TURN`), or
waking it would exceed the plan's concurrent runs
(`CONCURRENCY_LIMIT_REACHED`).

### 422

`stop_turn` only: the runtime could not confirm the stop (`STOP_TURN_UNCONFIRMED`).

## Example response (200)

```json
{
  "ok": true,
  "status": "cancelled"
}
```