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

<AgentInstructions>

## Submitting Feedback

If you encounter incorrect, outdated, or confusing documentation on this page, submit feedback:

POST https://docs.poly.ai/feedback

```json
{
  "path": "/api-reference/concurrent-calls/introduction",
  "feedback": "Description of the issue"
}
```

Only submit feedback when you have something specific and actionable to report.

</AgentInstructions>

# Concurrent Calls API

> Track concurrent conversations over time for capacity planning and monitoring.

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

| Region | Base URL                                                                       |
| -----: | ------------------------------------------------------------------------------ |
|     US | [https://api.us-1.platform.polyai.app](https://api.us-1.platform.polyai.app)   |
|     UK | [https://api.uk-1.platform.polyai.app](https://api.uk-1.platform.polyai.app)   |
|    EUW | [https://api.euw-1.platform.polyai.app](https://api.euw-1.platform.polyai.app) |

Example:
`GET https://api.uk-1.platform.polyai.app/v1/ACCOUNT-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:

| Value     | Description                                                      |
| --------- | ---------------------------------------------------------------- |
| `variant` | Separate series per variant with `variant_id` and `variant_name` |

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.