# mv.insights

> The insights methods of @morevoice/sdk: Conversation analytics.

Conversation analytics. These methods are on `mv.insights`, where `mv` is your client (see [the Node.js SDK](https://docs.morevoice.ai/sdk/node/#connect)). Each one returns the response object and throws when the API answers with an error.

## `retrieve()`

**Retrieve conversation insights.** Analytics over the period's scored calls: KPIs, dispositions, the top objections and the answers that win, behaviour buckets and per-agent trends.

```ts
mv.insights.retrieve(query?: NonNullable<InsightsRetrieveData["query"]>, options?: RequestOptions): Promise<InsightsRetrieveResponse>
```

`GET /insights` · [API reference](https://docs.morevoice.ai/api/operations/insights_retrieve/)

### Parameters

| Name | Type | Required | Description |
| --- | --- | --- | --- |
| `query.days` | `integer` | no | The period: the last N days (1–365, default 30). |
| `query.agent_id` | `string` | no | Only this agent's calls. |
| `options.headers["MoreVoice-Version"]` | `string` | no | The API version to use for this request. Defaults to the version the API key is pinned to. |
| `options` | `RequestOptions` | no | `idempotencyKey`, extra `headers` and an abort `signal`: see [retries and idempotency](https://docs.morevoice.ai/sdk/typescript/retries/). |

### Returns

`Insights`:

| Field | Type | Description |
| --- | --- | --- |
| `object` | `"insights"` | Always `insights`. |
| `livemode` | `boolean` | `true` in live mode, `false` in test mode. |
| `days` | `integer` | — |
| `from` | `string` | An ISO-8601 timestamp in UTC. |
| `to` | `string` | An ISO-8601 timestamp in UTC. |
| `semantic_clustering` | `boolean` | Objections were grouped by meaning (false: by words — always in test mode). |
| `kpis` | `object` | — |
| `dispositions` | `object[]` | — |
| `top_objections` | `object[]` | — |
| `behaviour` | `object` | Win rate and score by agent behaviour. |
| `agents` | `object[]` | — |
| `copilot` | `object \| null` | Agent copilot usage. |

### Example

```ts
import MoreVoice from "@morevoice/sdk";

const mv = new MoreVoice(); // MOREVOICE_API_KEY from the environment

const insights = await mv.insights.retrieve();
console.log(insights);
```