Alerts API | PolyAI Platform

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.

API keys are not yet available through self-service. To request access, contact your PolyAI representative.

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