---
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/alerts/configure-alerts
  - /docs/cli/global-options
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
---

# 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. Run `vercel monitors notifications --help` for its subcommands. |

### `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.

## 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)
- [`--team`](/docs/cli/global-options#team)
- [`--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).


---

[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.