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.
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 list which rules are currently firing.
Key features
- Alert rules - Monitor metrics like turn latency, API errors, function errors, call crashes, and call volume
- Active alerts - Query which rules are currently in the
alert state
- 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 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 |
- 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"
}'
api.us.poly.ai with the base URL for your deployment region. See Getting started for the full list of regional base URLs.
2. Check active alerts
curl https://api.us.poly.ai/v1/alerts \
-H "x-api-key: YOUR_API_KEY"
Authentication
All Alerts API endpoints use API key authentication with 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 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
