Alerts API

Manage alert rules and query active alerts firing on your PolyAI agents.

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

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

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. 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.

Create a key from the API Keys tab in Agent Studio — see API keys.

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"
    }
  ]
}

Pagination

List endpoints currently return all results without pagination. For accounts with many alert rules, 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:

{
  "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