> ## Documentation Index
> Fetch the complete documentation index at: https://docs.coval.ai/llms.txt
> Use this file to discover all available pages before exploring further.

# Alerts

> Manage alerts and their evaluation events with the Coval CLI

Alerts evaluate metric conditions when a run completes and notify a channel (Slack, email, webhook, or a Human Review project) when they trigger. The CLI command is `coval monitors`; the product and the API call these alerts, and the command name is kept for compatibility.

`create` and `update` also accept `--input-json` (inline JSON, `@file`, or `-` for stdin); explicit flags override fields from the JSON. See [Input JSON](/cli/agent-mode#input-json).

## List Alerts

```bash theme={null}
coval monitors list [OPTIONS]
```

| Option        | Type   | Default | Description                                                                    |
| ------------- | ------ | ------- | ------------------------------------------------------------------------------ |
| `--scope`     | string | —       | Filter by scope: `ALL`, `SIMULATION`, or `MONITORING` (uploaded conversations) |
| `--page-size` | number | 50      | Results per page                                                               |
| `--order-by`  | string | —       | Sort order                                                                     |

**Output columns:** ID, Name, Status, Scope, Evaluation, Triggers

```bash theme={null}
coval monitors list
```

## Get Alert

```bash theme={null}
coval monitors get <monitor_id>
```

| Argument     | Type   | Required | Description  |
| ------------ | ------ | -------- | ------------ |
| `monitor_id` | string | **Yes**  | The alert ID |

## Create Alert

```bash theme={null}
coval monitors create [OPTIONS]
```

| Option                      | Type   | Required | Description                                                                                    |
| --------------------------- | ------ | -------- | ---------------------------------------------------------------------------------------------- |
| `--name`                    | string | **Yes**  | Human-readable alert name                                                                      |
| `--evaluation-type`         | string | **Yes**  | When the alert is evaluated (`ON_RUN_COMPLETE`)                                                |
| `--conditions`              | JSON   | **Yes**  | JSON array of conditions (see below). The CLI rejects a create without conditions              |
| `--description`             | string | No       | Description                                                                                    |
| `--scope`                   | string | No       | Which runs the alert applies to: `ALL`, `SIMULATION`, or `MONITORING` (uploaded conversations) |
| `--match-mode`              | string | No       | `ALL` (every condition must be met) or `ANY`                                                   |
| `--cooldown-seconds`        | number | No       | Minimum seconds between triggers (0-86400)                                                     |
| `--custom-message-template` | string | No       | Custom notification text                                                                       |
| `--agent-ids`               | string | No       | Comma-separated agent IDs to restrict the alert to                                             |
| `--required-tags`           | string | No       | Comma-separated run tags a run must carry to be evaluated                                      |
| `--scheduled-run-ids`       | string | No       | Comma-separated scheduled run IDs to restrict the alert to                                     |
| `--channels`                | JSON   | No       | JSON array of notification channels (see below)                                                |

### Conditions

Each condition is an object with a `metric_id`, an `aggregation` (`SINGLE`, `RUN_AVERAGE`, or `RUN_FRACTION`), an `operator` (`GT`, `GTE`, `LT`, `LTE`, `EQ`, `NEQ`), and a threshold (`threshold_float` or `threshold_string`). Fraction conditions can add `match_value` and `match_mode` (`exact`, `contains`, `contains_case_insensitive`); rolling windows use `window_size_days` or `window_size_runs`.

### Channels

Each channel is an object with a `channel_type` (`SLACK`, `EMAIL`, `WEBHOOK`, or `HUMAN_REVIEW`) and a `config` object, for example `{"recipients": ["team@company.com"]}` for `EMAIL` or `{"channel_id": "C0123ABC", "channel_name": "#alerts"}` for `SLACK`.

```bash theme={null}
coval monitors create \
  --name "Resolution rate dropped" \
  --evaluation-type ON_RUN_COMPLETE \
  --scope SIMULATION \
  --agent-ids ag_abc123 \
  --conditions '[{"metric_id":"met_abc123","aggregation":"RUN_AVERAGE","operator":"LT","threshold_float":0.8}]' \
  --channels '[{"channel_type":"EMAIL","config":{"recipients":["oncall@company.com"]}}]' \
  --cooldown-seconds 3600
```

## Update Alert

```bash theme={null}
coval monitors update <monitor_id> [OPTIONS]
```

| Argument     | Type   | Required | Description            |
| ------------ | ------ | -------- | ---------------------- |
| `monitor_id` | string | **Yes**  | The alert ID to update |

| Option                      | Type   | Description                                           |
| --------------------------- | ------ | ----------------------------------------------------- |
| `--name`                    | string | New name                                              |
| `--description`             | string | New description                                       |
| `--scope`                   | string | `ALL`, `SIMULATION`, or `MONITORING`                  |
| `--match-mode`              | string | `ALL` or `ANY`                                        |
| `--cooldown-seconds`        | number | Minimum seconds between triggers (0-86400)            |
| `--custom-message-template` | string | Custom notification text                              |
| `--agent-ids`               | string | Comma-separated agent IDs (replaces existing)         |
| `--required-tags`           | string | Comma-separated run tags (replaces existing)          |
| `--scheduled-run-ids`       | string | Comma-separated scheduled run IDs (replaces existing) |
| `--conditions`              | JSON   | JSON array of conditions (replaces existing)          |
| `--channels`                | JSON   | JSON array of channels (replaces existing)            |

```bash theme={null}
coval monitors update 01HXYZ1234567890ABCDEF --cooldown-seconds 7200
```

## Delete Alert

```bash theme={null}
coval monitors delete <monitor_id>
```

| Argument     | Type   | Required | Description            |
| ------------ | ------ | -------- | ---------------------- |
| `monitor_id` | string | **Yes**  | The alert ID to delete |

## Test an Alert Against a Run

Evaluate an alert's conditions against a completed run without sending notifications.

```bash theme={null}
coval monitors test-evaluate <monitor_id> --run-id <run_id>
```

| Argument     | Type   | Required | Description  |
| ------------ | ------ | -------- | ------------ |
| `monitor_id` | string | **Yes**  | The alert ID |

| Option     | Type   | Required | Description                 |
| ---------- | ------ | -------- | --------------------------- |
| `--run-id` | string | **Yes**  | The run to evaluate against |

```bash theme={null}
coval monitors test-evaluate 01HXYZ1234567890ABCDEF --run-id run_abc123
```

## Alert Events

List the evaluations recorded for an alert.

```bash theme={null}
coval monitors events <monitor_id> list [OPTIONS]
```

| Argument     | Type   | Required | Description  |
| ------------ | ------ | -------- | ------------ |
| `monitor_id` | string | **Yes**  | The alert ID |

| Option        | Type   | Default | Description                                                         |
| ------------- | ------ | ------- | ------------------------------------------------------------------- |
| `--outcome`   | string | —       | Filter by outcome: `TRIGGERED`, `NOT_MET`, `SUPPRESSED`, or `ERROR` |
| `--page-size` | number | 50      | Results per page                                                    |

**Output columns:** Event ID, Monitor ID, Run ID, Outcome

```bash theme={null}
coval monitors events 01HXYZ1234567890ABCDEF list --outcome TRIGGERED
```