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

# Alerts API

> Monitor agent performance in real time and receive webhook notifications when latency, errors, or volume thresholds are breached.

The Alerts API lets you monitor your voice agents in real time and react to performance issues. Configure rules to watch key metrics like latency, errors, and call volume, then receive signed webhook notifications when thresholds breach.

## Key features

* **Alert rules** - Monitor metrics like turn latency, API errors, function errors, call crashes, and call volume
* **[Webhook notifications](/api-reference/webhooks/introduction)** - Receive signed HTTP POST requests when alerts trigger or resolve
* **Project scoping** - Scope alerts to specific projects or monitor account-wide

## Limits

| Resource    | Maximum per account |
| ----------- | ------------------- |
| Alert rules | 10                  |

Requests to create an alert rule beyond the limit return a `409 Conflict` error.

## Available metrics

All count-based metrics represent **absolute counts in the evaluation window**, not rates. For example, if you set `window_duration: "5m"` and `threshold_value: 10` for `api_errors`, the alert triggers when there are 10 or more API errors in the 5-minute window.

| Metric             | Description                                   | Unit         | Typical threshold guidance            |
| ------------------ | --------------------------------------------- | ------------ | ------------------------------------- |
| `turn_latency_p50` | Median turn latency                           | milliseconds | 800-1500ms depending on use case      |
| `turn_latency_p95` | 95th percentile turn latency                  | milliseconds | 1500-3000ms depending on use case     |
| `api_errors`       | Number of API errors in window                | count        | Consider 0 for critical flows         |
| `function_errors`  | Number of function execution errors in window | count        | Consider 0 for critical functions     |
| `call_crashes`     | Number of call crashes in window              | count        | Typically 0 (any crash is concerning) |
| `call_volume`      | Number of calls in window                     | count        | Depends on expected traffic patterns  |

When setting thresholds, consider the metric type and business impact:

* **Error metrics** (`api_errors`, `function_errors`, `call_crashes`): Consider setting threshold to 0 for critical flows where any error requires attention
* **Latency metrics**: Use longer windows (5-15 minutes) to smooth out transient spikes
* **Volume metrics**: Base thresholds on historical traffic patterns and expected business hours

## Alert states

| State     | Description                                                   | When it occurs                                                                 |
| --------- | ------------------------------------------------------------- | ------------------------------------------------------------------------------ |
| `ok`      | The metric is within the configured threshold                 | After successful evaluation shows metric below threshold                       |
| `alert`   | The metric has breached the threshold and the alert is firing | Metric exceeds threshold during evaluation                                     |
| `no_data` | No data is available for evaluation                           | No metric data reported during the evaluation window (e.g., no calls)          |
| `unknown` | The state could not be determined                             | The alert rule has not yet been evaluated or the evaluation could not complete |

**`no_data` vs `unknown`:** Use `no_data` to detect when your agents aren't receiving traffic (which may itself be a problem). `unknown` indicates that the state could not be determined — for example, the rule has not yet been evaluated. New alert rules default to the `ok` state until their first evaluation.

## Quick start

### 1. Create an alert rule

```bash theme={"theme":{"light":"github-light","dark":"github-dark"}}
curl -X POST https://api.us.poly.ai/v1/alert-rules \
  -H "x-api-key: YOUR_API_KEY" \
  -H "Content-Type: application/json" \
  -d '{
    "name": "High turn latency (p95)",
    "project_id": "proj_abc123",
    "metric": "turn_latency_p95",
    "operator": ">=",
    "threshold_value": 1500,
    "window_duration": "5m"
  }'
```

Replace `api.us.poly.ai` with the base URL for your deployment region. See [Getting started](/api-reference/introduction#regional-api-endpoints) for the full list of regional base URLs.

### 2. Register a webhook endpoint

```bash theme={"theme":{"light":"github-light","dark":"github-dark"}}
curl -X POST https://api.us.poly.ai/v1/webhook-endpoints \
  -H "x-api-key: YOUR_API_KEY" \
  -H "Content-Type: application/json" \
  -d '{
    "name": "Production alert notifications",
    "url": "https://example.com/webhooks/polyai",
    "event_types": ["alerts.triggered", "alerts.resolved"]
  }'
```

<Warning>
  The `signing_secret` is returned only once when you create a webhook endpoint. Store it securely immediately.

  **Lost your signing secret?** Use the [rotate signing secret](/api-reference/webhooks/endpoint/rotate-webhook-signing-secret) endpoint to generate a new one.
</Warning>

### 3. Check active alerts

```bash theme={"theme":{"light":"github-light","dark":"github-dark"}}
curl https://api.us.poly.ai/v1/alerts \
  -H "x-api-key: YOUR_API_KEY"
```

## Webhook delivery

When an alert triggers or resolves, PolyAI sends a signed HTTP POST to your registered [webhook endpoints](/api-reference/webhooks/introduction).

| Event              | Description                                             |
| ------------------ | ------------------------------------------------------- |
| `alerts.triggered` | Sent when an alert rule transitions into a firing state |
| `alerts.resolved`  | Sent when a firing alert transitions back to `ok`       |

### Example payloads

<Tabs>
  <Tab title="alerts.triggered">
    ```json theme={"theme":{"light":"github-light","dark":"github-dark"}}
    {
      "event_type": "alerts.triggered",
      "alert": {
        "id": "ar_0Kx4mNpQ8rWvYb2dFgHjLs",
        "name": "High turn latency (p95)",
        "project_id": "proj_abc123",
        "metric": "turn_latency_p95",
        "operator": ">=",
        "threshold_value": 1500,
        "current_value": 1823,
        "previous_state": "ok",
        "triggered_at": "2024-03-15T10:30:00Z"
      }
    }
    ```
  </Tab>

  <Tab title="alerts.resolved">
    ```json theme={"theme":{"light":"github-light","dark":"github-dark"}}
    {
      "event_type": "alerts.resolved",
      "alert": {
        "id": "ar_0Kx4mNpQ8rWvYb2dFgHjLs",
        "name": "High turn latency (p95)",
        "project_id": "proj_abc123",
        "metric": "turn_latency_p95",
        "operator": ">=",
        "threshold_value": 1500,
        "current_value": 920,
        "previous_state": "alert",
        "resolved_at": "2024-03-15T10:45:00Z"
      }
    }
    ```
  </Tab>
</Tabs>

For webhook delivery details including headers, retry policy, and signature verification, see the [Webhooks API](/api-reference/webhooks/introduction).

## Authentication

All Alerts API endpoints use API key authentication with the `x-api-key` header. Resources are automatically scoped to your account.

<Note>
  API keys are not yet available through self-service. To request access, email [developers@poly.ai](mailto:developers@poly.ai).
</Note>

```bash theme={"theme":{"light":"github-light","dark":"github-dark"}}
curl https://api.us.poly.ai/v1/alerts \
  -H "x-api-key: YOUR_API_KEY"
```

## Error responses

| Status | Description                                                                               |
| ------ | ----------------------------------------------------------------------------------------- |
| 400    | Validation error - check request body or parameters                                       |
| 401    | Missing or invalid API key                                                                |
| 404    | Resource not found                                                                        |
| 409    | Resource limit exceeded (e.g. maximum number of alert rules or webhook endpoints reached) |
| 422    | Validation error or malformed resource ID                                                 |
| 500    | Internal server error                                                                     |
| 502    | Monitoring backend sync failure                                                           |

### Example error response

```json theme={"theme":{"light":"github-light","dark":"github-dark"}}
{
  "message": "Validation failed",
  "errors": [
    {
      "field": "threshold_value",
      "message": "must be a non-negative integer"
    },
    {
      "field": "metric",
      "message": "must be one of: turn_latency_p50, turn_latency_p95, api_errors, function_errors, call_crashes, call_volume"
    }
  ]
}
```

## Pagination

List endpoints currently return all results without pagination. For accounts with many alert rules or webhook endpoints, consider filtering by `project_id`, `metric`, or `enabled` status to reduce response size.

## Update request format

PATCH requests use flat JSON, the same format as POST/create requests. Include only the fields you want to update:

```json theme={"theme":{"light":"github-light","dark":"github-dark"}}
{
  "threshold_value": 20,
  "enabled": false
}
```

## Window duration

The `window_duration` field accepts the following values:

| Value | Duration            |
| ----- | ------------------- |
| `5m`  | 5 minutes           |
| `10m` | 10 minutes          |
| `60m` | 60 minutes (1 hour) |

Recommended usage:

* **Latency alerts:** `5m` or `10m` to smooth out transient spikes
* **Error count alerts:** `5m` for faster detection
* **Volume alerts:** `10m` or `60m` depending on traffic patterns