# Signal Run

- **Method:** `POST`
- **Path:** `/api/v1/runs/{run_id}/{signal}`
- **Operation ID:** `signal_run`
- **Tags:** runs

Pause, resume or cancel a run in flight: the last path segment is `pause`, `resume` or `cancel`.

`pause` starts no new session and holds the running ones; `resume` releases a paused run, including one
that paused itself on reaching `budget.total_cost_usd`; `cancel` stops the running sessions, starts no
more, and ends the run `cancelled` without judging what they did. A run that has already finished is a
409\.

## Effective servers

- `https://api.saram.sh`

  Saram

## Authentication

- **HTTPBearer**: HTTP bearer

  a Saram API key (`sk_saram_<env>_...`) or a person's AuthKit access token, as `Authorization: Bearer <credential>`. Both are told apart by shape and produce the same principal.

## Path parameters

- **`run_id` (required)**: `string`
- **`signal` (required)**: `string`

## Responses

### 202 The signal is delivered to the run.

**Content type:** `application/json`

schema: `RunSignalled`, no additional properties

A pause, resume or cancel delivered to a run.

- **`run_id` (required)**: `string`

  The run the signal was delivered to.
- **`signal` (required)**: `string`

  The signal delivered: pause, resume or cancel.

**Example:**

```json
{
  "run_id": "",
  "signal": ""
}
```

### 403 the API key lacks the required scope

### 422 Validation Error

**Content type:** `application/json`

schema: `HTTPValidationError`

- **`detail`**: `array`

  **Items:**

  schema: `ValidationError`
  - **`loc` (required)**: `array of (string | integer)`
  - **`msg` (required)**: `string`
  - **`type` (required)**: `string`
  - **`ctx`**: `object`
  - **`input`**: `any`

**Example:**

```json
{
  "detail": [
    {
      "loc": [
        ""
      ],
      "msg": "",
      "type": "",
      "input": null,
      "ctx": {}
    }
  ]
}
```

## Schemas

- `HTTPValidationError` — shown above.
- `RunSignalled` — shown above.
- `ValidationError` — shown above.