The Alerts API lets you monitor your voice agents in real time. Configure alert rules to watch key operational metrics, then receive webhook notifications when something goes wrong.
Key features
- Alert rules - Monitor metrics like turn latency, API errors, function errors, call crashes, and call volume
- Webhook notifications - 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 |
409 Conflict error.
Available metrics
All count-based metrics represent absolute counts within 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
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 for the full list of regional base URLs. 2. Register a webhook endpoint
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"]
}'
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 endpoint to generate a new one. 3. Check active alerts
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.
| 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
alerts.triggered
alerts.resolved
{
"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"
}
}
{
"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"
}
}
Authentication
All Alerts API endpoints use API key authentication via the x-api-key header. Resources are automatically scoped to your account.
API keys are not yet available through self-service. To request access, email developers@poly.ai. 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
{
"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"
}
]
}
project_id, metric, or enabled status to reduce response size.
PATCH requests use flat JSON, the same format as POST/create requests. Include only the fields you want to update:
{
"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) |
- 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
