> ## Documentation Index
> Fetch the complete documentation index at: https://polyai-mintlify-41fdf97b.mintlify.site/llms.txt
> Use this file to discover all available pages before exploring further.
# Capabilities
> Reference for every tool the PolyAI Data MCP server exposes, grouped by capability, with request parameters and expected response shapes for each one.
Data MCP exposes PolyAI's conversation data as MCP tools. Your client discovers them automatically on connection — you don't configure tools by hand. Each tool carries its own input schema, which the client reads directly from the server; the parameter tables below reproduce that schema so you can see what each tool takes without connecting first.
Data MCP exposes **5 tools**. Tool names appear exactly as your client sees them in `tools/list`.
To see exactly what your client discovered, ask it to list its tools or query the endpoint's `tools/list` method. Parameters map to a PolyAI REST endpoint — they're sent as path segments, query parameters, or a request body — but your client handles that wiring from the schema; the tables below just list what you can set.
## Search & read conversations
Find conversations by their metrics, search across transcript text, and pull back the full turn-by-turn record.
### `search-conversations`
Search conversations by metric filters, with sorting and pagination.
| Parameter | Type | Description |
| ------------------ | -------- | ------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------- |
| `from` / `to` | datetime | Bounds on conversation start time (`from` inclusive, `to` exclusive). |
| `filters` | array | Metric filters: `{metric, op, value}`. Operators: `eq`, `gt`, `gte`, `lt`, `lte`, `in`, `ex`, `contains`, `not_contains`, `exists`. `conversation_id` is also accepted as a filter (`eq`/`in`) to fetch one or many conversations' metrics. |
| `filter_operator` | string | How filters combine: `and` (default) or `or`. |
| `fields` | array | Metric keys to include in each conversation's `metrics` map (case-insensitive). Omit to return all metrics — prefer passing only the metrics you need, especially on large searches. |
| `channel` | array | Restrict to channels: `VOICE-SIP`, `CHAT`, `WEBCHAT`, `SMS`, `RCS`. |
| `client_env` | array | Restrict to environments: `test`, `sandbox`, `pre-release`, `live`, `scenarios`. |
| `sort` | object | `{field, order}` — field is `started_at`, `duration`, or `conversation_id`. Defaults to `started_at` descending. |
| `limit` / `offset` | integer | Pagination. `limit` 1–100 (default 20), `offset` 0–1000. |
| `project_id` | string | Optional project scope. |
### `search-transcripts`
Full-text search over transcript turns across conversations, returning matches with surrounding turns for context.
| Parameter | Type | Description |
| ------------------ | -------- | -------------------------------------------------------- |
| `q` | string | Search phrase, 3–300 characters. **Required.** |
| `from` / `to` | datetime | Bounds on conversation start time. |
| `context_turns` | integer | Turns of context around each match, 0–3 (default 1). |
| `limit` / `offset` | integer | Pagination. `limit` 1–100 (default 20), `offset` 0–1000. |
| `project_id` | string | Project scope. Required when authenticating with a PAT. |
### `get-conversation`
Fetch every turn of a single conversation.
| Parameter | Type | Description |
| ----------------- | ------ | ---------------------------------------- |
| `conversation_id` | string | The conversation to fetch. **Required.** |
| `project_id` | string | Optional project scope. |
## Metrics & analytics
Discover which metrics you can filter and aggregate on, then roll one up over time into buckets you can chart.
### `get-metrics`
List the filterable metrics for an account, optionally scoped to a project — built-in metrics plus any custom metrics the project defines. Use this first to discover what you can filter and aggregate on.
| Parameter | Type | Description |
| ------------ | ------ | ----------------------- |
| `project_id` | string | Optional project scope. |
### `aggregate-metrics`
Aggregate a metric over a time window into buckets you can chart — with grouping, cohort filters, and post-aggregation thresholds.
This tool is **experimental** — its schema may change. Your client discovers the current name from `tools/list`.
| Parameter | Type | Description |
| ------------------------------ | -------- | ----------------------------------------------------------------------------------------------------------------------------------------------------- |
| `metric` | string | Metric to aggregate (case-insensitive, e.g. `poly_score`). **Required.** |
| `aggs` | array | Aggregations to compute: `sum`, `avg`, `min`, `max`, `p50`, `p95`, `p99`, `conversation_count`, `distinct_count`. **Required.** |
| `from` / `to` | datetime | Window bounds (`from` inclusive, `to` exclusive). |
| `interval` | string | Time bucket: `hourly`, `daily`, `weekly`, `monthly`. Omit for a single unbucketed result. |
| `timezone` | string | IANA timezone (e.g. `Europe/London`) applied to `hourly` and `daily` bucketing; naive `from`/`to` are interpreted in it. Ignored for other intervals. |
| `group_by` | array | Group by `project_id`, `channel`, `deployment_id`, `variant_id`, `client_env`, or — for string metrics — `value_string`. |
| `filters` | array | Cohort filters on other metrics: `{metric, op, value}`. Operators: `eq`, `gt`, `gte`, `lt`, `lte`, `in`, `ex`, `exists`. |
| `filter_operator` | string | How filters combine: `and` (default) or `or`. |
| `having` | array | Post-aggregation thresholds: `{field, op, value}` where `field` is one of the `aggs`. |
| `channel` | array | Restrict to channels: `VOICE-SIP`, `CHAT`, `WEBCHAT`, `SMS`, `RCS`. |
| `client_env` | array | Restrict to environments: `test`, `sandbox`, `pre-release`, `live`, `scenarios`. |
| `deployment_id` / `variant_id` | array | Restrict to specific deployments or variants. |
| `sort` | object | Secondary sort on a `group_by` or `aggs` field, applied after the ascending bucket sort. |
| `limit` / `offset` | integer | Pagination. `limit` 1–100 (default 20), `offset` 0–1000. |
| `project_id` | string | Optional project scope. |
## Errors
| Status | Meaning |
| ------ | ------------------------------------------------------------------------------------- |
| `400` | Request validation error. |
| `401` | Missing or invalid `X-API-KEY`. |
| `403` | Authenticated, but missing the required permission. |
| `404` | Not found or empty result — also returned when a credential can't access the account. |
| `422` | Unsupported filter. |