---
title: vercel monitors
product: vercel
url: /docs/cli/monitors
canonical_url: "https://vercel.com/docs/cli/monitors"
last_updated: 2026-10-26
type: reference
prerequisites:
  - /docs/cli
related:
  - /docs/alerts
  - /docs/cli/alerts
  - /docs/cli/login
  - /docs/cli
  - /docs/alerts/configure-alerts
summary: Create, list, inspect, update, and delete monitors for projects and teams with the Vercel CLI.
install_vercel_plugin: npx plugins add vercel/vercel-plugin
search_with_vercel_cli: npx vercel@latest docs search "<query>"
---

# vercel monitors

The `vercel monitors` command manages monitors (the rules that decide when Vercel [alerts](/docs/alerts) your team) from the terminal. It replaces the deprecated [`vercel alerts rules`](/docs/cli/alerts#rules) command tree.

Use [monitor schemas](#schema) to inspect the fields available to your selected team, then create, list, inspect, update, or delete monitors.

Use `vercel monitors --help` to see the command tree.

Monitor IDs are returned by `monitors add` and shown by `monitors ls`. Use those IDs with `monitors inspect`, `monitors update`, and `monitors rm`.

## Usage

```bash filename="terminal"
# List monitors for the linked project
vercel monitors ls

# Add a monitor from a JSON body file
vercel monitors add --project my-app --body ./monitor.json
```

*Using the \`vercel monitors\` command to list monitors and add a monitor.*

## Subcommands

| Command | Aliases | Description |
| --- | --- | --- |
| `ls` | `list` | List monitors for a project or team. |
| `schema` | None | Show available monitor types, request fields, constraints, and examples. |
| `add` | `create` (deprecated) | Add a monitor from a JSON body file. |
| `inspect` | `get` | Show one monitor by ID. |
| `rm` | `remove`, `delete` | Delete a monitor. |
| `update` | `patch` | Patch a monitor or change its project scope. |
| `notifications` | None | List and manage the Slack channels and webhooks linked to monitors. See [notification commands](#notifications). |

### `ls`

List monitors that affect the linked project. Use `--project` to select another project or `--all` to list every accessible monitor in the selected team.

Aliases: `list`.

```bash filename="terminal"
vercel monitors ls
```

#### Options

| Option | Description |
| --- | --- |
| `-p, --project` | List monitors that affect a project by name or ID, for example `my-app` or `prj_abc123`. |
| `-a, --all` | List every accessible monitor in the selected team. |
| `--type` | Filter by monitor type. The option is repeatable and accepts comma-separated values. |
| `--format` | Output format. Supports `json`. |

Use `built-in` to list built-in monitors. For compatibility with previous CLI versions, `monitors ls --type` also accepts supported built-in trigger types such as `usage_anomaly` and `error_anomaly`. Use `vercel monitors schema --type built-in` to inspect the trigger types available to your team.

Use `custom` to list custom monitors. For compatibility with previous CLI versions, the option also accepts `custom_alert`.

#### List monitor examples

```bash filename="terminal"
# List monitors for the linked project
vercel monitors ls

# List every monitor in the selected team
vercel monitors ls --all

# JSON output
vercel monitors ls --all --format json
```

List custom monitors affecting a specific project:

```bash filename="terminal"
vercel monitors ls --project my-app --type custom
```

`monitors ls` retrieves every available page before printing results. JSON output contains a `monitors` array with the matching monitor objects.

### `schema`

Fetch the API-owned authoring schema for the monitor types available to the selected team. Run the command without `--type` to list the available types, or select a type to see its create and update fields, constraints, and examples.

```bash filename="terminal"
vercel monitors schema
```

#### Options

| Option | Description |
| --- | --- |
| `--type` | Monitor type to describe. |
| `--format` | Output format. Supports `json`. |

#### Monitor schema examples

```bash filename="terminal"
# Show the fields and examples for built-in monitors
vercel monitors schema --type built-in
```

Show the fields and examples for custom monitors:

```bash filename="terminal"
vercel monitors schema --type custom
vercel monitors schema --type custom --format json
```

For custom monitors, run `vercel metrics schema <metric-or-prefix>` before authoring the body. The command returns current metric names, aggregations, dimensions, and filter fields. Use a returned metric name directly in `evaluation.query.metrics.<alias>.metric`.

### `add`

Add a monitor from a JSON body file. The request body must set `type`. For a built-in monitor, set `type` to `built-in`. For a custom monitor, set `type` to `custom`.

`create` remains a deprecated compatibility alias, but prints a deprecation warning. Use `add` for new commands.

```bash filename="terminal"
vercel monitors add --project my-app --body ./monitor.json
```

#### Options

| Option | Description |
| --- | --- |
| `--body` | Path to a JSON file containing the new monitor. |
| `-p, --project` | Apply a monitor to one project. |
| `-a, --all` | Apply a built-in monitor to every project in the selected team. |
| `--format` | Output format. Supports `json`. |

Custom monitors require `--project` and do not support `--all`.

#### Add monitor body examples

Create a JSON file for the monitor body, then select the monitor's project scope in one of these ways:

- Add `ruleScope` to the body.
- Pass `--project <name-or-id>`.
- Pass `--all` for a built-in monitor.

Do not combine `ruleScope` with `--project` or `--all`. A linked project does not supply the scope automatically when you add a monitor.

Add a built-in error anomaly monitor for one project:

```json filename="monitor.json"
{
  "type": "built-in",
  "name": "Production server errors",
  "triggers": {
    "mode": "selected",
    "items": [
      {
        "type": "error_anomaly",
        "filter": "statusGroup:5xx AND route:/api/*"
      }
    ]
  },
  "matchMinimumSeverityLevel": "high"
}
```

```bash filename="terminal"
vercel monitors add --project my-app --body ./monitor.json
```

Use `vercel monitors schema --type built-in` for additional validated examples, filter syntax, and current constraints.

Add a custom threshold monitor for one project:

```json filename="monitor.json"
{
  "type": "custom",
  "name": "Checkout server errors",
  "severity": "high",
  "evaluation": {
    "window": "5m",
    "query": {
      "metrics": {
        "errors": {
          "metric": "vercel.request.count",
          "aggregation": "count",
          "filter": "httpStatus >= 500"
        }
      },
      "outputs": ["errors"]
    }
  },
  "trigger": {
    "type": "threshold",
    "output": "errors",
    "operator": "gt",
    "threshold": 20
  }
}
```

```bash filename="terminal"
vercel monitors add --project my-app --body ./monitor.json
```

Use `vercel monitors schema --type custom` for additional validated examples, filter syntax, and current constraints.

#### Migrate previous rule bodies

The current command rejects request bodies that contain the previous `alertTypes` field. Rewrite saved bodies using the current schema:

| Previous shape | Current shape |
| --- | --- |
| `alertTypes` | Top-level `type` and, for built-in monitors, `triggers` |
| `projectId` expression or raw project ID | `ruleScope`, `--project`, or `--all` |
| `autosubscribeOwnersInKnock` | `notificationSettings.enableTeamOwnerNotifications` |

Built-in filters use the syntax shown by the current schema. For example, an error anomaly filter uses `statusGroup:5xx` instead of the previous OData expression.

#### Migrate previous custom rule bodies

The current command also rejects request bodies that contain the previous `customAlert` or `queryJsonString` fields. Rewrite custom monitor fields using the current schema:

| Previous shape | Current shape |
| --- | --- |
| `customAlert.queryJsonString` | `evaluation.query` object |
| `triggerType`, `triggerOperator`, and `triggerThreshold` | `trigger` object |
| `formula.left` and `formula.right` | `evaluation.query.formulas` and `evaluation.query.outputs` |

Custom filters use the syntax shown by the current schema.

### `inspect`

Show one monitor by ID.

Aliases: `get`.

Monitor IDs are unique within a team. Use the global `--scope <team>` option when the monitor belongs to a team other than your current team.

```bash filename="terminal"
vercel monitors inspect <monitorId>
```

#### Arguments

| Name | Description |
| --- | --- |
| `monitorId` | Required. ID of the monitor to inspect. |

#### Options

| Option | Description |
| --- | --- |
| `--format` | Output format. Supports `json`. |

#### Inspect monitor examples

```bash filename="terminal"
vercel monitors inspect ar_abc123
vercel monitors inspect ar_abc123 --format json
```

### `rm`

Delete a monitor. The selected team's default monitor cannot be deleted.

Aliases: `remove`, `delete`.

Monitor IDs are unique within a team. Use the global `--scope <team>` option when the monitor belongs to a team other than your current team.

```bash filename="terminal"
vercel monitors rm <monitorId>
```

#### Arguments

| Name | Description |
| --- | --- |
| `monitorId` | Required. ID of the monitor to delete. |

#### Options

| Option | Description |
| --- | --- |
| `--format` | Output format. Supports `json`. |
| `-y, --yes` | Skip the confirmation prompt. |

#### Delete monitor examples

```bash filename="terminal"
# Delete with confirmation
vercel monitors rm ar_abc123

# Delete without prompt
vercel monitors rm ar_abc123 --yes

# Delete by using the delete alias
vercel monitors delete ar_abc123 --yes
```

### `update`

Patch a monitor from a JSON body file, change its project scope, or do both. Omitted body fields remain unchanged, and `type` is optional because the API infers it from the stored monitor.

Aliases: `patch`.

```bash filename="terminal"
vercel monitors update <monitorId> --body ./patch.json
vercel monitors update <monitorId> --project my-app
```

#### Arguments

| Name | Description |
| --- | --- |
| `monitorId` | Required. ID of the monitor to update. |

#### Options

| Option | Description |
| --- | --- |
| `--body` | Path to a partial JSON file with fields to update. |
| `-p, --project` | Apply a monitor to one project. |
| `-a, --all` | Apply a built-in monitor to every project in the selected team. |
| `--format` | Output format. Supports `json`. |

You must provide `--body`, `--project`, or `--all`. Do not combine a `ruleScope` field in the body with `--project` or `--all`.

Custom monitors require `--project` and do not support `--all`.

#### Update monitor examples

Save the fields you want to change in a JSON file:

```json filename="patch.json"
{
  "name": "Critical production errors",
  "matchMinimumSeverityLevel": "critical"
}
```

```bash filename="terminal"
# Update fields from a file
vercel monitors update ar_abc123 --body ./patch.json

# Patch by using the patch alias
vercel monitors patch ar_abc123 --body ./patch.json

# Change scope without a body file
vercel monitors update ar_abc123 --project my-app
```

The authoring schema includes restrictions based on the stored monitor. For example, the default monitor accepts notification updates only.

A custom monitor with `querySupported: false` accepts changes to `name`, `severity`, and `notificationSettings` only.

### `notifications`

List and manage the Slack channels and account webhooks linked to monitors. Sign in with [`vercel login`](/docs/cli/login), or [authenticate with a token](/docs/cli#using-in-a-cicd-environment). Commands use your selected team, including the team from a linked project. Pass `--scope <team>` to select another team.

Notification commands don't require a linked project. In non-interactive mode, pass `--scope` explicitly unless the directory is linked to a team project; the CLI doesn't use a saved default team. Without a monitor ID, listing returns destinations for every readable monitor in the team, even when you run it from a linked project directory.

| Command | Description |
| --- | --- |
| `notifications ls [monitorId]` | List destinations for all readable monitors or one monitor. Alias: `list`. |
| `notifications link <monitorId>` | Link an existing Slack channel or account webhook. |
| `notifications update <monitorId>` | Change a linked destination's delivery setting. The `patch` alias is deprecated. |
| `notifications unlink <monitorId>` | Remove a destination's link to a monitor. |

#### List notification destinations

Running `notifications` without a subcommand runs `ls`. You can also pass a monitor ID directly:

```bash filename="terminal"
vercel monitors notifications
vercel monitors notifications ls ar_example
vercel monitors notifications ar_example --json
```

*List destinations for the selected team or one monitor.*

The CLI retrieves every page before printing the team-wide result. Slack destinations include the channel and installation IDs. Webhook destinations include the webhook ID and, when available to your account, its details. Use these IDs to update or unlink a destination.

#### Link a destination

For Slack, [install the Vercel app and invite it to your channel](/docs/alerts/configure-alerts#configure-slack-for-a-monitor) before linking the channel:

```bash filename="terminal"
vercel monitors notifications link ar_example --slack-channel C123
vercel monitors notifications link ar_example --slack-channel C123 --slack-installation-id icfg_example
```

*Link a Slack channel, selecting its installation when needed.*

You can omit `--slack-installation-id` only when the team has exactly one completed Slack installation. Otherwise, the command returns an error asking for the installation ID.

To link an existing account webhook, pass its ID rather than its URL. Use [`vercel webhooks list`](/docs/cli/webhooks) to find webhook IDs, or see [Configure webhooks](/docs/alerts/configure-alerts#configure-webhooks) to set one up:

```bash filename="terminal"
vercel monitors notifications link ar_example --webhook wh_example
vercel monitors notifications link ar_example --webhook wh_example --critical-only
```

*Link a webhook with the monitor's delivery setting or restrict it to Critical alerts.*

By default, a new link follows the monitor's delivery setting. Add `--critical-only` to notify the destination only when Vercel Agent escalates an alert to Critical.

#### Update delivery settings

Use `--critical-only` to restrict an existing destination, or `--no-critical-only` to remove that override and follow the monitor's delivery setting:

```bash filename="terminal"
vercel monitors notifications update ar_example --slack-channel C123 --critical-only
vercel monitors notifications update ar_example --webhook wh_example --no-critical-only
```

*Change whether a linked destination receives only Critical alerts.*

`update` requires exactly one of these two options. It changes the selected destination's delivery setting without unlinking it or changing the monitor's matching conditions.

#### Unlink a destination

Remove the link to a Slack channel or webhook:

```bash filename="terminal"
vercel monitors notifications unlink ar_example --slack-channel C123
vercel monitors notifications unlink ar_example --webhook wh_example
```

*Stop sending this monitor's notifications to a destination.*

Unlinking removes the monitor's destination link; it doesn't delete the account webhook or uninstall the Slack app. The `link`, `update`, and `unlink` commands apply changes without a confirmation prompt.

#### Notification options

| Option | Commands | Description |
| --- | --- | --- |
| `--slack-channel <CHANNEL_ID>` | `link`, `update`, `unlink` | Select a Slack channel by ID. Use either this option or `--webhook`. |
| `--slack-installation-id <INSTALLATION_ID>` | `link`, `update`, `unlink` | Select the Slack installation. Requires `--slack-channel`; optional only when the team has exactly one completed installation. |
| `--webhook <WEBHOOK_ID>` | `link`, `update`, `unlink` | Select an account webhook by ID. Can't be combined with either Slack option. |
| `--critical-only` | `link`, `update` | Deliver only alerts escalated to Critical by Vercel Agent. |
| `--no-critical-only` | `update` | Remove the destination's Critical-only restriction. Can't be combined with `--critical-only`. |
| `--json`, `--format json` | All notification commands | Write structured JSON to stdout. |

Every mutation requires a monitor ID and exactly one destination. Run separate commands to manage multiple destinations.

#### Notification JSON output

| Command | Result fields |
| --- | --- |
| `notifications ls` | `notifications`, an object mapping monitor IDs to destination arrays. |
| `notifications ls <monitorId>` | `notifications`, an array of destinations for that monitor. |
| `notifications link`, `notifications update`, `notifications unlink` | `success` and `notification`, the affected destination. |

In [non-interactive mode](/docs/cli/global-options#non-interactive), responses also include `status`, `message`, and suggested `next` commands. Per-monitor results include `monitorId`, and mutations include `action`.

For example, with [jq](https://jqlang.org/) installed, extract the destinations for one monitor:

```bash filename="terminal"
vercel monitors notifications ar_example --json | jq '.notifications'
```

*Read a monitor's destination array from JSON output.*

## JSON output

Use `--format json` for scripting and automation. Monitor commands write only JSON to standard output:

| Command | Output shape |
| --- | --- |
| `monitors ls` | `{ "monitors": [...] }` |
| `monitors schema` | `{ "schemaVersion": number, "monitorTypes": [...] }` |
| `monitors add`, `monitors inspect`, `monitors update` | `{ "monitor": {...} }` |
| `monitors rm` | `{ "ok": true, "monitorId": "ar_...", "deleted": true }` |

Validation failures return an `error` object with `code` and `message`. When the API identifies individual invalid fields, the object also includes an `issues` array with field paths and messages.

## Migrate from `vercel alerts rules`

`vercel monitors` replaces the deprecated [`vercel alerts rules`](/docs/cli/alerts#rules) command tree. The options and request bodies are unchanged:

| Previous command | Current command |
| --- | --- |
| `vercel alerts rules ls` | `vercel monitors ls` |
| `vercel alerts rules schema` | `vercel monitors schema` |
| `vercel alerts rules create` | `vercel monitors add` |
| `vercel alerts rules inspect` | `vercel monitors inspect` |
| `vercel alerts rules rm` | `vercel monitors rm` |
| `vercel alerts rules update` | `vercel monitors update` |

JSON output renames the `rule` keys to `monitor` keys: `rules` becomes `monitors`, `ruleTypes` becomes `monitorTypes`, `rule` becomes `monitor`, and `ruleId` becomes `monitorId`. Update scripts that read these fields when you migrate. See [JSON output](#json-output) for the current shapes.

## Related resources

- To learn how to configure and receive alerts, see [Alerts](/docs/alerts).
- To configure monitors from the dashboard, see [Configure alerts](/docs/alerts/configure-alerts).
- To list and inspect the alerts your monitors raise, see [`vercel alerts`](/docs/cli/alerts).

## Global Options

The following [global options](/docs/cli/global-options) can be passed when using the `vercel monitors` command:

- [`--cwd`](/docs/cli/global-options#current-working-directory)
- [`--debug`](/docs/cli/global-options#debug)
- [`--global-config`](/docs/cli/global-options#global-config)
- [`--help`](/docs/cli/global-options#help)
- [`--local-config`](/docs/cli/global-options#local-config)
- [`--no-color`](/docs/cli/global-options#no-color)
- [`--non-interactive`](/docs/cli/global-options#non-interactive)
- [`--scope`](/docs/cli/global-options#scope)
- [`--token`](/docs/cli/global-options#token)
- [`--version`](/docs/cli/global-options#version)

For more information on global options and their usage, refer to the [options section](/docs/cli/global-options).

## Search the docs from your terminal

Search the Vercel docs and read pages as Markdown with the Vercel CLI. No login required.

```bash
# Find docs pages by keyword
npx vercel@latest docs search "environment variables"
npx vercel@latest docs search "function timeout"

# Print a docs page as Markdown, by path or URL
npx vercel@latest docs inspect <page>
```

---

[View full sitemap](/docs/sitemap)


If you encounter incorrect information, can’t find what you need, need a capability Vercel doesn’t currently offer, or have any other feedback to report, please do it by following the instructions at https://vercel.com/feedback.md.
