# uip insights alerts

> Syntax and options for `uip insights alerts`, which reads UiPath Insights real-time alert definitions.

`uip insights alerts` reads UiPath Insights real-time alert definitions — the alert rules configured in Insights, not the history of when they fired (see [alert-history](./uip-insights-alert-history.md) for that). This is a read-only surface: there is no create, update, or delete verb.

:::note
These routes are feature-gated to Cloud and Dedicated SaaS deployments. On other deployment types the command fails with a `ConfigError` stating the routes aren't served, rather than an empty result.
:::

## Synopsis

```text
uip insights alerts list [--agentic --process-key <key>] [-l <n>] [-o <n>]
uip insights alerts get <alert-id>
uip insights alerts check-entitlement
```

All verbs honor the [global options](./global-options.md) and the standard [exit codes](./exit-codes.md). None of these verbs accept `-t, --tenant` — they use the tenant selected during `uip login`.

## uip insights alerts list

List alert definitions visible to the current caller. Pass `--agentic` to list the definitions scoped to one process key instead of the tenant-wide list.

### Options

| Flag | Description |
|---|---|
| `--agentic` | Use the agentic route, scoped to one process key. Requires `--process-key`. |
| `--process-key <key>` | Process key to scope the agentic list to. Only valid with `--agentic`; passing it without `--agentic` is a validation error. |
| `-l, --limit <number>` | Maximum rows to return. Defaults to `50`. |
| `-o, --offset <number>` | Rows to skip before returning results. |

Pagination is client-side: the backend returns the full unpaginated list, and the CLI slices it after fetching.

### Examples

```bash
uip insights alerts list

uip insights alerts list --agentic --process-key MyAgenticProcess

uip insights alerts list --limit 10 --offset 10
```

### Data shape

```json
{
  "Code": "InsightsAlertsList",
  "Data": [
    {
      "id": 42,
      "name": "High failure rate",
      "severity": "ERROR",
      "isActive": true,
      "engine": "aggregate",
      "metric": "FailedJobCount",
      "metricState": "Failed",
      "operator": "GreaterThan",
      "threshold": 5,
      "windowSeconds": 3600,
      "deliveryId": 7,
      "autoSnoozeSeconds": 1800,
      "snoozedUntil": null,
      "lastTriggeredAt": 1714003200,
      "processKey": "Invoicing",
      "folderKey": "f0f0f0f0-0000-0000-0000-000000000001",
      "projectKey": null,
      "processVersion": "1.0.0",
      "scopes": [{ "field": "FolderName", "values": ["Finance"] }]
    }
  ],
  "Pagination": { "Returned": 1, "Limit": 50, "Offset": 0, "Total": 1, "HasMore": false }
}
```

Rows are a closed allow-list projection — fields not shown here (like the raw stored query) are never emitted. Field names are camelCase, unlike the PascalCase convention used by most other `uip` commands. When `engine` is an aggregate-type alert, the row may also include `condition` (a human-readable rendering of the alert's trigger condition) and `conditionVisible` (whether that rendering was available).

## uip insights alerts get

Get one alert definition by its integer ID.

### Arguments

- `<alert-id>` *(required)* — the alert definition's integer ID (from `alerts list`).

### Example

```bash
uip insights alerts get 42
```

### Data shape

Same row shape as one element of `alerts list`'s `Data` array, under `Code: "InsightsAlertGet"`.

```json
{
  "Code": "InsightsAlertGet",
  "Data": {
    "id": 42,
    "name": "High failure rate",
    "severity": "ERROR",
    "isActive": true,
    "engine": "aggregate",
    "metric": "FailedJobCount",
    "metricState": "Failed",
    "operator": "GreaterThan",
    "threshold": 5,
    "windowSeconds": 3600,
    "deliveryId": 7,
    "autoSnoozeSeconds": 1800,
    "snoozedUntil": null,
    "lastTriggeredAt": 1714003200,
    "processKey": "Invoicing",
    "folderKey": "f0f0f0f0-0000-0000-0000-000000000001",
    "projectKey": null,
    "processVersion": "1.0.0",
    "scopes": []
  }
}
```

A 404 here means the alert ID doesn't exist in the current tenant — pass a valid ID from `alerts list`.

## uip insights alerts check-entitlement

Check whether the current tenant is confirmed entitled to Insights alerts.

### Example

```bash
uip insights alerts check-entitlement
```

### Data shape

```json
{
  "Code": "InsightsAlertEntitlement",
  "Data": { "entitled": true }
}
```

A 403 on `alerts list`/`alerts get` usually means the caller's Orchestrator folder access couldn't be resolved rather than an entitlement problem — check the active tenant and folder permissions first, and use `check-entitlement` as a follow-up to confirm entitlement specifically.

## Related

- [alert-history](./uip-insights-alert-history.md) — when an alert fired, as opposed to how it's defined.
- [alert-deliveries](./uip-insights-alert-deliveries.md) — where an alert notification is sent (the `deliveryId` on a row here).

## See also

- [Insights overview](./uip-insights.md)