# Retrieve conversation insights

`GET https://api.morevoice.ai/v1/insights`

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

Authenticate with a secret API key: `Authorization: Bearer $MOREVOICE_API_KEY`.

Operation ID: `insights_retrieve`.

## Parameters

### Query parameters

| Name | Type | Required | Description |
| --- | --- | --- | --- |
| `days` | `integer` | no | The period: the last N days (1–365, default 30). |
| `agent_id` | `string` | no | Only this agent's calls. |

### Headers

| Name | Type | Required | Description |
| --- | --- | --- | --- |
| `MoreVoice-Version` | `string` | no | The API version to use for this request. Defaults to the version the API key is pinned to. |

## Responses

### 200 OK

OK Returns `Insights`.

| Field | Type | Description |
| --- | --- | --- |
| `object` | `"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` | — |
| `kpis.analyzed` | `integer` | Calls with a finished scorecard. |
| `kpis.average_score` | `number \| null` | — |
| `kpis.pass_rate` | `number \| null` | — |
| `kpis.compliance_fail_rate` | `number \| null` | — |
| `kpis.win_rate` | `number \| null` | Share of calls with a positive disposition (sale, appointment…). |
| `kpis.average_duration_seconds` | `number \| null` | — |
| `dispositions` | `object[]` | — |
| `top_objections` | `object[]` | — |
| `behaviour` | `object` | Win rate and score by agent behaviour. |
| `behaviour.talk_ratio` | `object[]` | — |
| `behaviour.questions` | `object[]` | — |
| `behaviour.checklist` | `object[] \| null` | — |
| `agents` | `object[]` | — |
| `copilot` | `object \| null` | Agent copilot usage. |
| `copilot.adoption_rate` | `number \| null` | — |
| `copilot.thumbs_up` | `integer` | — |
| `copilot.thumbs_down` | `integer` | — |

Example:

```json
{
  "agents": [
    {
      "average_score": 83.2,
      "calls": 87,
      "compliance_fails": 0,
      "name": "Dana Levi",
      "pass_rate": 0.9,
      "user_id": "usr_2Lm8Pq4Rt6Vx0Zb3Nd5Fh7",
      "weekly": [
        {
          "average_score": 84.5,
          "calls": 21,
          "week": "2026-10-25"
        }
      ],
      "win_rate": 0.31
    }
  ],
  "behaviour": {
    "checklist": null,
    "questions": [
      {
        "average_score": 84,
        "calls": 98,
        "label": "5–8",
        "win_rate": 0.38
      }
    ],
    "talk_ratio": [
      {
        "average_score": 82.1,
        "calls": 120,
        "label": "35–55%",
        "win_rate": 0.34
      }
    ]
  },
  "copilot": {
    "adoption_rate": 0.42,
    "thumbs_down": 4,
    "thumbs_up": 31
  },
  "days": 30,
  "dispositions": [
    {
      "calls": 64,
      "disposition": "appointment"
    }
  ],
  "from": "2026-10-04T09:14:22.000Z",
  "kpis": {
    "analyzed": 412,
    "average_duration_seconds": 245,
    "average_score": 78.4,
    "compliance_fail_rate": 0.03,
    "pass_rate": 0.81,
    "win_rate": 0.27
  },
  "livemode": true,
  "object": "insights",
  "semantic_clustering": true,
  "to": "2026-11-03T09:14:22.000Z",
  "top_objections": [
    {
      "best_response": "Compared it with today's costs.",
      "calls": 51,
      "count": 58,
      "examples": [
        "It's too expensive"
      ],
      "handled_rate": 0.72,
      "label": "Too expensive",
      "win_rate": 0.22,
      "win_rate_handled": 0.29,
      "win_rate_unhandled": 0.06
    }
  ]
}
```

### 400 Bad Request

The request is invalid: a parameter is missing, malformed or unknown, or the version header is unknown. Returns `ErrorEnvelope`.

### 401 Unauthorized

No valid API key was sent. Returns `ErrorEnvelope`.

### 403 Forbidden

The key may not do this (a missing scope, a plan limit, or a compliance block). Returns `ErrorEnvelope`.

### 429 Too Many Requests

Too many requests, or no call capacity right now. Retry after the Retry-After delay. Returns `ErrorEnvelope`.

### 500 Internal Server Error

Something went wrong on MoreVoice's side. Retry with the same Idempotency-Key. Returns `ErrorEnvelope`.

## Code samples

**TypeScript**

```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);
```

**Python**

```python
from morevoice import MoreVoice

client = MoreVoice()  # MOREVOICE_API_KEY from the environment

insights = client.insights.retrieve()
print(insights)
```

**cURL**

```sh
curl https://api.morevoice.ai/v1/insights \
  -H "Authorization: Bearer $MOREVOICE_API_KEY"
```