Skip to content
MoreVoiceDevelopers

Preview report data

POST
/reports/preview
import MoreVoice from "@morevoice/sdk";


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


const reportPreview = await mv.reports.preview({
  language: "en",
  period: "last7",
  widgets: [
    {
      key: "w1",
      type: "kpis",
    },
  ],
});
console.log(reportPreview);

Computes widgets for a period now and returns the data (nothing is stored or sent). With cadence, also the next three send times. Needs a live key.

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

Authorizations

Section titled “Authorizations”

Parameters

Section titled “Parameters”

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
Idempotency-Key
string
>= 1 characters <= 255 characters

A unique key (for example a UUID) that makes this request safe to retry: for 24 hours, a retry with the same key and parameters returns the first response instead of acting twice.

Example
5f0c1e8a-7b2d-4c3e-9f1a-2b6d8e4c0a17

Request Bodyrequired

Section titled “Request Bodyrequired”
Media typeapplication/json
object
cadence

A cadence to list the next three send times for.

object
day_of_month

Monthly: 1–31, or -1 for the last day.

integer
>= -1 <= 31
days

Weekly: at least one weekday.

Array<string>
>= 1 items <= 7 items
Allowed values: sun mon tue wed thu fri sat
frequency
required
string
Allowed values: daily weekly monthly
time
required
string
/^([01]\d|2[0-3]):[0-5]\d$/
timezone

Default Asia/Jerusalem.

string
>= 1 characters <= 64 characters
filters
object
agent_ids
Array<string>
<= 200 items
assistant_ids
Array<string>
<= 200 items
campaign_ids
Array<string>
<= 200 items
flow_ids
Array<string>
<= 200 items
queue_ids
Array<string>
<= 200 items
team_ids
Array<string>
<= 200 items
language

The language of labels in the result (default en).

string
Allowed values: he en
period

The window each report covers, in its time zone: today, yesterday, last7, last30, thisWeek, lastWeek, thisMonth or lastMonth. Default yesterday.

string
Allowed values: today yesterday last7 last30 thisWeek lastWeek thisMonth lastMonth
timezone

Default Asia/Jerusalem.

string
>= 1 characters <= 64 characters
widgets
required
Array<object>
>= 1 items <= 20 items
object
key
required

Your key for the widget (unique in the report).

string
>= 1 characters <= 40 characters
params
object
limit
integer
>= 1 <= 50
sla_sec
integer
>= 5 <= 600
title
string
<= 120 characters
type
required
string
Allowed values: kpis volume queues agents ai cost campaigns qa ivr callbacks dnc
Example
{
  "language": "en",
  "period": "last7",
  "widgets": [
    {
      "key": "w1",
      "type": "kpis"
    }
  ]
}

Responses

Section titled “Responses”

200

Section titled “200”

OK

Media typeapplication/json

A report’s data computed now, as it would be sent.

object
generated_at
required

An ISO-8601 timestamp in UTC.

string format: date-time
livemode
required

true in live mode, false in test mode.

boolean
object
required
string
Allowed value: report_preview
period
required
object
from
required

An ISO-8601 timestamp in UTC.

string format: date-time
label
required
string
Allowed values: today yesterday last7 last30 thisWeek lastWeek thisMonth lastMonth
timezone
required
string
to
required

An ISO-8601 timestamp in UTC.

string format: date-time
upcoming_runs
required

The next three send times of cadence, when one was sent.

Array<string>
widgets
required
Array<object>
object
chart
required
Any of:
object
categories
required
Array<string>
category_format
required
string | null
currency
required
string | null
format
required
string
kind
required
string
line
required
Any of:
object
label
required
string
values
required
Array<number | null>
series
required
Array<object>
object
label
required
string
values
required
Array<number>
empty
required

No data in the period.

boolean
error
required

The widget could not be computed (the others still are).

string | null
key
required

The widget’s key.

string
kpis
required
Array<object>
object
currency
required
string | null
delta
required

Change against the previous period of the same length (0.12 = +12 %).

number | null
format
required

Int, pct (0–1), dur (seconds), money (minor units), num, text or date.

string
key
required

A stable label key.

string
label
required
string
up_is_good
required
boolean | null
value
required
number | null
note
required
string | null
table
required
Any of:
object
columns
required
Array<object>
object
currency
required
string | null
format
required
string
key
required
string
label
required
string
rows
required
Array<object>
object
key
additional properties
string | number | null
title
required
string
type
required
string
Allowed values: kpis volume queues agents ai cost campaigns qa ivr callbacks dnc
Example
{
  "generated_at": "2026-11-04T09:00:00.000Z",
  "livemode": true,
  "object": "report_preview",
  "period": {
    "from": "2026-10-27T22:00:00.000Z",
    "label": "last7",
    "timezone": "Asia/Jerusalem",
    "to": "2026-11-03T22:00:00.000Z"
  },
  "upcoming_runs": [],
  "widgets": [
    {
      "chart": null,
      "empty": false,
      "error": null,
      "key": "w1",
      "kpis": [
        {
          "currency": null,
          "delta": 0.08,
          "format": "int",
          "key": "reports.k.calls",
          "label": "Calls",
          "up_is_good": true,
          "value": 1240
        }
      ],
      "note": null,
      "table": null,
      "title": "Call overview",
      "type": "kpis"
    }
  ]
}

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.

409

Section titled “409”

The request conflicts with the object’s state, or the Idempotency-Key was reused with other parameters.

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": "idempotency_mismatch",
    "doc_url": "https://docs.morevoice.ai/api/errors#idempotency-mismatch",
    "message": "This Idempotency-Key was already used with different parameters.",
    "request_id": "req_7Hk2LmN9pQ4rS6tV8wX0yZ",
    "type": "idempotency_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.