---
title: "Aggregate Conversation Insights"
method: GET
path: "/ai/conversations/conversation-insights/aggregates"
tags: ["Conversations"]
---

# Aggregate Conversation Insights

`GET /ai/conversations/conversation-insights/aggregates`

## Request

- Base URL: `https://api.telnyx.com/v2`
- URL: `https://api.telnyx.com/v2/ai/conversations/conversation-insights/aggregates`
- Auth: HTTP bearer

Aggregate conversation insights by specified fields

## Query parameters

- `group_by` string[]: Fields to group by (can be comma-separated or multiple parameters). Prefix a field with 'metadata.' (e.g. 'metadata.assistant_id') to group by the conversation's metadata instead of the insight result. Common fields used for over-time charts: - `score` — Group by the insight's score value (e.g. for Agent Instruction Following, User Satisfaction). - `metadata.assistant_id` — Group by the assistant that handled the conversation. - `metadata.assistant_version_id` — Group by the assistant version, useful for comparing performance across versions in the portal's 'Insights Over Time' chart. - `metadata.telnyx_conversation_channel` — Group by conversation channel (phone_call, web_chat, etc.).
- `show` string[]: Fields to include in the result (can be comma-separated or multiple parameters). Supports the same 'metadata.<key>' prefix as group_by. Each returned row will contain the grouped field values plus a `record_count` indicating how many conversation insights match that combination.
- `insight_id` string, uuid: Optional insight ID to filter conversation insights. Only insights matching this ID will be included in the aggregation.
- `created_at` string: Filter by creation datetime to scope the aggregation window. Supports range operators (e.g., `created_at=gte.2025-01-01T00:00:00Z` for the start of the range, `created_at=lt.2025-01-02T00:00:00Z` for the end). To build per-day time series (as the portal does for the 'Insights Over Time' chart), issue one request per day bounded by `created_at=gte.<day_start>` and `created_at=lt.<next_day_start>`.
- `metadata.assistant_id` string: Filter by assistant ID (e.g., `metadata.assistant_id=eq.<assistant_id>`). When provided, only conversation insights for the specified assistant are aggregated. Used by the portal to scope the 'Insights Over Time' chart to a single assistant.

## Response `200`

Successful Response

- ConversationInsightAggregateResp: Aggregated conversation insight counts grouped by the specified fields. Each item in `data` contains the grouped field values and a `record_count` indicating how many conversation insights match that combination.
  - `data` object[], required: Aggregation result rows. Each row contains the grouped field values and a `record_count`.
    - `record_count` integer, required: Number of conversation insights that match this combination of grouped field values.

## Other responses

- `422`: Validation Error

## Changes

- **2026-10-15** `a72569d69430`: 1 info
  - endpoint added

[Operation history](https://skmtc.dev/team-telnyx/apis/telnyx-api/changes/ai/conversations/conversation-insights/aggregates/get.md)

---

[API](https://skmtc.dev/team-telnyx/apis/telnyx-api.md) - [All operations](https://skmtc.dev/team-telnyx/apis/telnyx-api/llms.txt) - [OpenAPI document](https://skmtc.dev/team-telnyx/apis/telnyx-api/revisions/0f17b8167873?raw)