Concurrent Calls API

The Concurrent Calls API lets you measure concurrent conversations and analyze traffic patterns over time. It returns a time series of 5-minute intervals with peak concurrency, filtered by environment, variant, language, phone number, and more–useful for capacity planning and monitoring.

Endpoint

GET https://api.{region}.platform.polyai.app/v1/{account_id}/{project_id}/conversations/concurrency

Where:

• region is one of: us-1, uk-1, euw-1
• account_id is your PolyAI account ID
• project_id is your PolyAI project ID

Example: GET https://api.<region>.platform.polyai.app/v1/ws-t53y16r3/PROJECT-f76d75c2/conversations/concurrency

Required query parameters

• start_time Start of the reporting window in ISO8601 format. Rounded down to the nearest 5-minute mark.

• end_time End of the reporting window in ISO8601 format. Rounded up to the nearest 5-minute mark.

start_time and end_time must be no more than one week apart.

Optional filters

• client_env Filter by environment: sandbox, pre-release or live. Defaults to live.

• variant_id / variant_name Filter to a single variant by ID or name (only one may be supplied).

• language Filter to a specific language code (for example en-GB).

• phone_number Filter to a specific phone number.

Slicing results

Use the slice_by parameter to break down the time series:

Additional slicing options (such as language and phone_number) may be added in the future.

When slice_by is set, each interval in the response includes additional context fields such as variant_id and variant_name.

Authentication

All requests must include an API key in the x-api-key header. The key must be authorized for the Conversations and analytics endpoints for the specified account and project.

Example header: x-api-key: YOUR_API_KEY

Response structure

On success, the API returns:

• account_id The account that was queried.

• project_id The project that was queried.

• intervals An array of 5-minute intervals in ascending chronological order. Each interval includes:

  • time: lower bound of the 5-minute window (UTC, ISO8601)
  • max_concurrent_conversations: maximum concurrent calls in that window after filters
  • variant_id and variant_name (when sliced by variant)
  • optional language or phone_number fields for future slicing support

You can use this time series to plot concurrency over time, to validate concurrency limits, or to correlate spikes with marketing campaigns and operational changes.

Error handling

Typical error responses include:

• 400 Bad Request
  Missing or invalid parameters (such as an invalid time range).

• 401 Unauthorized / 403 Forbidden
  Missing, invalid, or unauthorized API key.

• 404 Not Found
  Account or project not found.

• 500 or 501
  Internal errors or unimplemented combinations such as slice_by set to language or phone_number.

Log the error_message field in the response body to help diagnose issues.