Skip to main content
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 - Receive signed HTTP POST requests when alerts trigger or resolve
  • Project scoping - Scope alerts to specific projects or monitor account-wide

​
Limits

ResourceMaximum per account
Alert rules10
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.
MetricDescriptionUnitTypical threshold guidance
turn_latency_p50Median turn latencymilliseconds800-1500ms depending on use case
turn_latency_p9595th percentile turn latencymilliseconds1500-3000ms depending on use case
api_errorsNumber of API errors in windowcountConsider 0 for critical flows
function_errorsNumber of function execution errors in windowcountConsider 0 for critical functions
call_crashesNumber of call crashes in windowcountTypically 0 (any crash is concerning)
call_volumeNumber of calls in windowcountDepends 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

StateDescriptionWhen it occurs
okThe metric is within the configured thresholdAfter successful evaluation shows metric below threshold
alertThe metric has breached the threshold and the alert is firingMetric exceeds threshold during evaluation
no_dataNo data is available for evaluationNo metric data reported during the evaluation window (e.g., no calls)
unknownThe state could not be determinedThe 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.
EventDescription
alerts.triggeredSent when an alert rule transitions into a firing state
alerts.resolvedSent when a firing alert transitions back to ok

​
Example payloads

{
  "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"
  }
}
For webhook delivery details including headers, retry policy, and signature verification, see the Webhooks API.

​
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

StatusDescription
400Validation error - check request body or parameters
401Missing or invalid API key
404Resource not found
409Resource limit exceeded (e.g. maximum number of alert rules or webhook endpoints reached)
422Validation error or malformed resource ID
500Internal server error
502Monitoring 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 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: 
{
  "threshold_value": 20,
  "enabled": false
}

​
Window duration

The window_duration field accepts the following values:
ValueDuration
5m5 minutes
10m10 minutes
60m60 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
Last modified on April 20, 2026