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

# Aggregate Conversation Insights

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

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

---

[API](https://skmtc.net/team-telnyx/apis/telnyx-api-2.md) · [All operations](https://skmtc.net/team-telnyx/apis/telnyx-api-2/llms.txt) · [OpenAPI document](https://skmtc-service-staging.skmtc.workers.dev/v1/apis/team-telnyx/telnyx-api-2/revisions/ec31f78cf002/schema)