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

# Notifications & Alerts

> Proactive monitoring — automatic failure alerts plus custom alerts emitted from your agents

The **Notifications** system proactively monitors every agent execution and delivers alerts to the portal in real time — the bell in the top bar updates over WebSocket, no refresh needed. Failures are detected automatically, and your agent code can emit **custom alerts** with a single SDK call.

## Automatic alerts

The platform watches every execution and raises an alert without any instrumentation on your side:

| Alert type            | Triggered when                                                                                                                           | Severity | Typical latency |
| --------------------- | ---------------------------------------------------------------------------------------------------------------------------------------- | -------- | --------------- |
| **Execution failure** | An execution ends with an uncaught error (a `throw` that escapes your handler)                                                           | warning  | seconds         |
| **Execution timeout** | An execution exceeds the runtime cap, or gets stuck in `RUNNING` beyond the limit — including when the runtime itself crashed mid-flight | critical | under a minute  |
| **Connector failure** | A connector call fails, even if your code catches the error and the execution succeeds                                                   | warning  | seconds         |

<Note>
  Detection is two-layered: most alerts fire from the trace pipeline within seconds, and an independent watchdog reads the execution store directly — so a worker that dies without reporting anything still produces an alert. Both staging and production are monitored; every notification carries an environment badge.
</Note>

### Grouping and deduplication

Alerts are designed to inform, not to flood:

* The **first** failure of an agent notifies immediately.
* Subsequent failures of the same agent and type within a **15-minute window** increment the same notification ("12 failures in the last 15 min") instead of creating new ones.
* Each execution is counted **once**, even when detected by more than one path.
* Within a group, severity only escalates (a `critical` event upgrades a `warning` group, never the opposite).

## Custom alerts from the SDK

Available from `@runflow-ai/sdk` **v1.4.1**. Call `sendNotification()` anywhere inside an execution — no IDs required, everything is resolved from the execution context:

```typescript theme={null}
import { sendNotification } from '@runflow-ai/sdk';

// Simple warning (default severity)
sendNotification('Customer record missing in CRM');

// Critical alert with details
sendNotification('Stock depleted in ERP', {
  severity: 'critical',
  body: `SKU ${sku} returned zero availability during order flow`,
});

// Deduplicate by your own key: the same document only alerts once per execution
sendNotification('Invoice validation failed', {
  severity: 'warning',
  dedupeKey: invoiceId,
});
```

### Options

| Option      | Type                      | Default     | Description                                                                          |
| ----------- | ------------------------- | ----------- | ------------------------------------------------------------------------------------ |
| `severity`  | `'warning' \| 'critical'` | `'warning'` | Controls the notification severity; `critical` escalates an open alert group         |
| `body`      | `string`                  | —           | Extra detail shown in the notification body                                          |
| `dedupeKey` | `string`                  | —           | Distinct alerts within one execution deduplicate by this key (defaults to the title) |

### Behavior

* **Fire-and-forget** — `sendNotification()` never throws and never blocks your agent's execution.
* The alert title you pass becomes the notification title in the portal, grouped per agent like automatic alerts.
* Custom alerts appear with the type **Alert** in the bell and history filters.

<Note>
  `sendNotification()` is designed to run **inside the Runflow runtime**. Outside of it (a plain local script with no execution context), the alert is discarded server-side since there is no execution to attach it to.
</Note>

## Where notifications surface

<CardGroup cols={2}>
  <Card title="Notification bell" icon="bell">
    Real-time badge in the top bar. Click an alert to jump straight to the affected agent.
  </Card>

  <Card title="History" icon="clock-rotate-left">
    Full paginated history with filters: environment, type, severity and unread-only.
  </Card>

  <Card title="Agent health" icon="heart-pulse">
    The dashboard ranks all agents by health (error rate, timeouts, connector failures), and each agent's overview shows its health badge plus the most common errors, grouped and normalized.
  </Card>

  <Card title="Multi-tenant watchlist" icon="eye">
    Users with access to multiple tenants can pick which ones to watch — the bell aggregates alerts across all of them, tagged per tenant.
  </Card>
</CardGroup>

## Health metrics

The health views are computed from real execution data over a 24h/7d window:

* **Executions and failures** per agent (combining the trace layer with the execution store of record)
* **Error rate** with health classification: healthy (\<5%), degraded (5–20%), critical (≥20%)
* **Timeouts** and **stuck executions**
* **Connector failures** per agent
* **Most common errors**, grouped by normalized message (IDs and numbers collapsed so identical failures group together)