Skip to content
MoreVoiceDevelopers

Retrieve conversation insights

GET
/insights
import MoreVoice from "@morevoice/sdk";


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


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

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

Try it in the API playground with a test-mode key.

Authorizations

Section titled “Authorizations”

Parameters

Section titled “Parameters”

Query Parameters

Section titled “Query Parameters”
days
integer
default: 30 >= 1 <= 365

The period: the last N days (1–365, default 30).

agent_id
string
<= 200 characters /^usr_[0-9A-Za-z]+$/

Only this agent’s calls.

Header Parameters

Section titled “Header Parameters”
MoreVoice-Version
string
/^\d{4}-\d{2}-\d{2}$/

The API version to use for this request. Defaults to the version the API key is pinned to.

Example
2026-11-01

Responses

Section titled “Responses”

200

Section titled “200”

OK

Media typeapplication/json

Conversation analytics over the period’s scored calls: KPIs, objections and what wins, behaviour and agents.

object
agents
required
Array<object>
object
average_score
required
number | null
calls
required
integer
>= -9007199254740991 <= 9007199254740991
compliance_fails
required
integer
>= -9007199254740991 <= 9007199254740991
name
required
string
pass_rate
required
number | null
user_id
required
Any of:

A user ID (prefix usr_).

string
/^usr_[0-9A-Za-z]+$/
weekly
required
Array<object>
object
average_score
required
number | null
calls
required
integer
>= -9007199254740991 <= 9007199254740991
week
required

The week’s Sunday (YYYY-MM-DD).

string
win_rate
required
number | null
behaviour
required

Win rate and score by agent behaviour.

object
checklist
required
Any of:
Array<object>
object
average_score
required
number | null
calls
required
integer
>= -9007199254740991 <= 9007199254740991
label
required
string
win_rate
required
number | null
questions
required
Array<object>
object
average_score
required
number | null
calls
required
integer
>= -9007199254740991 <= 9007199254740991
label
required
string
win_rate
required
number | null
talk_ratio
required
Array<object>
object
average_score
required
number | null
calls
required
integer
>= -9007199254740991 <= 9007199254740991
label
required
string
win_rate
required
number | null
copilot
required
Any of:
object
adoption_rate
required
number | null
thumbs_down
required
integer
>= -9007199254740991 <= 9007199254740991
thumbs_up
required
integer
>= -9007199254740991 <= 9007199254740991
days
required
integer
>= -9007199254740991 <= 9007199254740991
dispositions
required
Array<object>
object
calls
required
integer
>= -9007199254740991 <= 9007199254740991
disposition
required
string
Allowed values: sale appointment callback_scheduled follow_up resolved unresolved not_interested escalated wrong_number no_conversation other
from
required

An ISO-8601 timestamp in UTC.

string format: date-time
kpis
required
object
analyzed
required

Calls with a finished scorecard.

integer
>= -9007199254740991 <= 9007199254740991
average_duration_seconds
required
number | null
average_score
required
number | null
compliance_fail_rate
required
number | null
pass_rate
required
number | null
win_rate
required

Share of calls with a positive disposition (sale, appointment…).

number | null
livemode
required

true in live mode, false in test mode.

boolean
object
required
string
Allowed value: insights
semantic_clustering
required

Objections were grouped by meaning (false: by words — always in test mode).

boolean
to
required

An ISO-8601 timestamp in UTC.

string format: date-time
top_objections
required
Array<object>
object
best_response
required

The answer that won most often.

string | null
calls
required
integer
>= -9007199254740991 <= 9007199254740991
count
required
integer
>= -9007199254740991 <= 9007199254740991
examples
required
Array<string>
handled_rate
required
number | null
label
required
string
win_rate
required
number | null
win_rate_handled
required
number | null
win_rate_unhandled
required
number | null
Example
{
  "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

Section titled “400”

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

Media typeapplication/json

Every /v1 error.

object
error
required
object
code
required

A stable, machine-readable code from the error-code catalogue.

string
details

Structured context, e.g. required_scope or the compliance verdict.

object
key
additional properties
doc_url
required

A link to the documentation of this code.

string
message
required

A human-readable explanation. Do not parse it.

string
param

The request parameter the error relates to, e.g. to or metadata[order_id].

string
request_id
required

The X-Request-Id of this request. Quote it when you contact support.

string
type
required

The category of the error.

string
Allowed values: invalid_request_error authentication_error permission_error not_found conflict rate_limit_error compliance_error idempotency_error api_error
Example
{
  "error": {
    "code": "parameter_missing",
    "doc_url": "https://docs.morevoice.ai/api/errors#parameter-missing",
    "message": "Missing required parameter: to.",
    "param": "to",
    "request_id": "req_7Hk2LmN9pQ4rS6tV8wX0yZ",
    "type": "invalid_request_error"
  }
}

Headers

Section titled “Headers”
X-Request-Id
string

The request’s ID (req_…). Quote it when you contact support.

401

Section titled “401”

No valid API key was sent.

Media typeapplication/json

Every /v1 error.

object
error
required
object
code
required

A stable, machine-readable code from the error-code catalogue.

string
details

Structured context, e.g. required_scope or the compliance verdict.

object
key
additional properties
doc_url
required

A link to the documentation of this code.

string
message
required

A human-readable explanation. Do not parse it.

string
param

The request parameter the error relates to, e.g. to or metadata[order_id].

string
request_id
required

The X-Request-Id of this request. Quote it when you contact support.

string
type
required

The category of the error.

string
Allowed values: invalid_request_error authentication_error permission_error not_found conflict rate_limit_error compliance_error idempotency_error api_error
Example
{
  "error": {
    "code": "invalid_api_key",
    "doc_url": "https://docs.morevoice.ai/api/errors#invalid-api-key",
    "message": "Invalid API key.",
    "request_id": "req_7Hk2LmN9pQ4rS6tV8wX0yZ",
    "type": "authentication_error"
  }
}

Headers

Section titled “Headers”
X-Request-Id
string

The request’s ID (req_…). Quote it when you contact support.

403

Section titled “403”

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

Media typeapplication/json

Every /v1 error.

object
error
required
object
code
required

A stable, machine-readable code from the error-code catalogue.

string
details

Structured context, e.g. required_scope or the compliance verdict.

object
key
additional properties
doc_url
required

A link to the documentation of this code.

string
message
required

A human-readable explanation. Do not parse it.

string
param

The request parameter the error relates to, e.g. to or metadata[order_id].

string
request_id
required

The X-Request-Id of this request. Quote it when you contact support.

string
type
required

The category of the error.

string
Allowed values: invalid_request_error authentication_error permission_error not_found conflict rate_limit_error compliance_error idempotency_error api_error
Example
{
  "error": {
    "code": "missing_scope",
    "doc_url": "https://docs.morevoice.ai/api/errors#missing-scope",
    "message": "This API key lacks the calls:write scope.",
    "request_id": "req_7Hk2LmN9pQ4rS6tV8wX0yZ",
    "type": "permission_error"
  }
}

Headers

Section titled “Headers”
X-Request-Id
string

The request’s ID (req_…). Quote it when you contact support.

429

Section titled “429”

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

Media typeapplication/json

Every /v1 error.

object
error
required
object
code
required

A stable, machine-readable code from the error-code catalogue.

string
details

Structured context, e.g. required_scope or the compliance verdict.

object
key
additional properties
doc_url
required

A link to the documentation of this code.

string
message
required

A human-readable explanation. Do not parse it.

string
param

The request parameter the error relates to, e.g. to or metadata[order_id].

string
request_id
required

The X-Request-Id of this request. Quote it when you contact support.

string
type
required

The category of the error.

string
Allowed values: invalid_request_error authentication_error permission_error not_found conflict rate_limit_error compliance_error idempotency_error api_error
Example
{
  "error": {
    "code": "rate_limited",
    "doc_url": "https://docs.morevoice.ai/api/errors#rate-limited",
    "message": "Too many requests. Retry after 1 second.",
    "request_id": "req_7Hk2LmN9pQ4rS6tV8wX0yZ",
    "type": "rate_limit_error"
  }
}

Headers

Section titled “Headers”
Retry-After
integer

Seconds to wait before retrying.

X-Request-Id
string

The request’s ID (req_…). Quote it when you contact support.

500

Section titled “500”

Something went wrong on MoreVoice’s side. Retry with the same Idempotency-Key.

Media typeapplication/json

Every /v1 error.

object
error
required
object
code
required

A stable, machine-readable code from the error-code catalogue.

string
details

Structured context, e.g. required_scope or the compliance verdict.

object
key
additional properties
doc_url
required

A link to the documentation of this code.

string
message
required

A human-readable explanation. Do not parse it.

string
param

The request parameter the error relates to, e.g. to or metadata[order_id].

string
request_id
required

The X-Request-Id of this request. Quote it when you contact support.

string
type
required

The category of the error.

string
Allowed values: invalid_request_error authentication_error permission_error not_found conflict rate_limit_error compliance_error idempotency_error api_error
Example
{
  "error": {
    "code": "internal_error",
    "doc_url": "https://docs.morevoice.ai/api/errors#internal-error",
    "message": "Something went wrong on MoreVoice's side.",
    "request_id": "req_7Hk2LmN9pQ4rS6tV8wX0yZ",
    "type": "api_error"
  }
}

Headers

Section titled “Headers”
X-Request-Id
string

The request’s ID (req_…). Quote it when you contact support.