# Preview report data

`POST https://api.morevoice.ai/v1/reports/preview`

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.

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

Operation ID: `reports_preview`.

## Parameters

### 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. |
| `Idempotency-Key` | `string` | no | 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. |

## Request body

Required, `application/json`.

| Field | Type | Required | Description |
| --- | --- | --- | --- |
| `widgets` | `object[]` | yes | — |
| `cadence` | `object` | no | A cadence to list the next three send times for. |
| `cadence.frequency` | `"daily" \| "weekly" \| "monthly"` | yes | — |
| `cadence.time` | `string` | yes | — |
| `cadence.day_of_month` | `integer` | no | monthly: 1–31, or -1 for the last day. |
| `cadence.days` | `("sun" \| "mon" \| "tue" \| "wed" \| "thu" \| "fri" \| "sat")[]` | no | weekly: at least one weekday. |
| `cadence.timezone` | `string` | no | Default Asia/Jerusalem. |
| `filters` | `object` | no | — |
| `filters.agent_ids` | `string[]` | no | — |
| `filters.assistant_ids` | `string[]` | no | — |
| `filters.campaign_ids` | `string[]` | no | — |
| `filters.flow_ids` | `string[]` | no | — |
| `filters.queue_ids` | `string[]` | no | — |
| `filters.team_ids` | `string[]` | no | — |
| `language` | `"he" \| "en"` | no | The language of labels in the result (default en). |
| `period` | `"today" \| "yesterday" \| "last7" \| "last30" \| "thisWeek" \| "lastWeek" \| "thisMonth" \| "lastMonth"` | no | The window each report covers, in its time zone: `today`, `yesterday`, `last7`, `last30`, `thisWeek`, `lastWeek`, `thisMonth` or `lastMonth`. Default yesterday. |
| `timezone` | `string` | no | Default Asia/Jerusalem. |

Example:

```json
{
  "language": "en",
  "period": "last7",
  "widgets": [
    {
      "key": "w1",
      "type": "kpis"
    }
  ]
}
```

## Responses

### 200 OK

OK Returns `ReportPreview`.

| Field | Type | Description |
| --- | --- | --- |
| `object` | `"report_preview"` | — |
| `livemode` | `boolean` | `true` in live mode, `false` in test mode. |
| `period` | `object` | — |
| `period.label` | `"today" \| "yesterday" \| "last7" \| "last30" \| "thisWeek" \| "lastWeek" \| "thisMonth" \| "lastMonth"` | — |
| `period.from` | `string` | An ISO-8601 timestamp in UTC. |
| `period.to` | `string` | An ISO-8601 timestamp in UTC. |
| `period.timezone` | `string` | — |
| `generated_at` | `string` | An ISO-8601 timestamp in UTC. |
| `widgets` | `object[]` | — |
| `upcoming_runs` | `string[]` | The next three send times of `cadence`, when one was sent. |

Example:

```json
{
  "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 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`.

### 409 Conflict

The request conflicts with the object's state, or the Idempotency-Key was reused with other parameters. 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 reportPreview = await mv.reports.preview({
	language: "en",
	period: "last7",
	widgets: [
		{
			key: "w1",
			type: "kpis",
		},
	],
});
console.log(reportPreview);
```

**Python**

```python
from morevoice import MoreVoice

client = MoreVoice()  # MOREVOICE_API_KEY from the environment

report_preview = client.reports.preview({
    "language": "en",
    "period": "last7",
    "widgets": [
        {
            "key": "w1",
            "type": "kpis",
        },
    ],
})
print(report_preview)
```

**cURL**

```sh
curl -X POST https://api.morevoice.ai/v1/reports/preview \
  -H "Authorization: Bearer $MOREVOICE_API_KEY" \
  -H "Content-Type: application/json" \
  -H "Idempotency-Key: $(uuidgen)" \
  -d '{
  "language": "en",
  "period": "last7",
  "widgets": [
    {
      "key": "w1",
      "type": "kpis"
    }
  ]
}'
```