> ## 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.
# Capabilities
> The tools Data MCP exposes, grouped by what they do — each with its parameters.
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`. |
| `filter_operator` | string | How filters combine: `and` (default) or `or`. |
| `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. |
### `-experimental--aggregate-a-metric-over-a-time-interval`
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 name (carrying the `-experimental-` prefix) and 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. |
| `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`. |
| `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. |