# mv.reports

> The reports methods of @morevoice/sdk: Scheduled reports, previews and runs.

Scheduled reports, previews and runs. These methods are on `mv.reports`, 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.

## `catalog()`

**List the report widgets.** The widgets a report can show, with the filters each honours; the periods and the cadences.

```ts
mv.reports.catalog(query?: NonNullable<ReportsCatalogData["query"]>, options?: RequestOptions): Promise<ReportsCatalogResponse>
```

`GET /reports/catalog` · [API reference](https://docs.morevoice.ai/api/operations/reports_catalog/)

### Parameters

| Name | Type | Required | Description |
| --- | --- | --- | --- |
| `query.language` | `string` | no | The language of names and descriptions (default en). |
| `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

`ReportCatalog`:

| Field | Type | Description |
| --- | --- | --- |
| `object` | `"report_catalog"` | Always `report_catalog`. |
| `widgets` | `object[]` | — |
| `periods` | `("today" \| "yesterday" \| "last7" \| "last30" \| "thisWeek" \| "lastWeek" \| "thisMonth" \| "lastMonth")[]` | — |
| `frequencies` | `("daily" \| "weekly" \| "monthly")[]` | — |

### Example

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

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

const reportCatalog = await mv.reports.catalog();
console.log(reportCatalog);
```

## `create()`

**Create a report.** Schedules a report: it is computed and emailed to its recipients on its cadence (the first send is `next_run_at`). Needs a live key.

```ts
mv.reports.create(body: ReportsCreateData["body"], options?: RequestOptions): Promise<ReportsCreateResponse>
```

`POST /reports` · [API reference](https://docs.morevoice.ai/api/operations/reports_create/)

### Parameters

| Name | Type | Required | Description |
| --- | --- | --- | --- |
| `body.name` | `string` | yes |  |
| `body.widgets` | `object[]` | yes |  |
| `body.cadence` | `object` | yes |  |
| `body.enabled` | `boolean` | no |  |
| `body.filters` | `object` | no |  |
| `body.formats` | `object` | no | Default: email and PDF. |
| `body.language` | `"he" \| "en"` | no | Default he. |
| `body.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. |
| `body.recipients` | `object[]` | no |  |
| `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.headers["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. |
| `options` | `RequestOptions` | no | `idempotencyKey`, extra `headers` and an abort `signal`: see [retries and idempotency](https://docs.morevoice.ai/sdk/typescript/retries/). |

### Returns

`Report`:

| Field | Type | Description |
| --- | --- | --- |
| `object` | `"report"` | Always `report`. |
| `id` | `string` | A report ID (prefix `rpt_`). |
| `livemode` | `boolean` | `true` in live mode, `false` in test mode. |
| `name` | `string` | — |
| `enabled` | `boolean` | Disabled reports are not sent on their schedule (they can still be sent now). |
| `widgets` | `object[]` | — |
| `period` | `"today" \| "yesterday" \| "last7" \| "last30" \| "thisWeek" \| "lastWeek" \| "thisMonth" \| "lastMonth"` | The window each report covers, in its time zone: `today`, `yesterday`, `last7`, `last30`, `thisWeek`, `lastWeek`, `thisMonth` or `lastMonth`. |
| `filters` | `object` | — |
| `cadence` | `object` | — |
| `recipients` | `object[]` | — |
| `formats` | `object` | — |
| `language` | `"he" \| "en"` | — |
| `owner_id` | `string \| null` | `usr_…` ID. |
| `next_run_at` | `string \| null` | — |
| `last_run_at` | `string \| null` | — |
| `last_run` | `object \| null` | The latest run (list responses only; null on others). |
| `created` | `string` | An ISO-8601 timestamp in UTC. |
| `updated` | `string` | An ISO-8601 timestamp in UTC. |

### Example

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

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

const report = await mv.reports.create({
	cadence: {
		frequency: "daily",
		time: "08:00",
		timezone: "Asia/Jerusalem",
	},
	formats: {
		email: true,
		pdf: true,
	},
	name: "Daily contact-centre summary",
	period: "yesterday",
	recipients: [
		{
			type: "email",
			value: "ops@example.com",
		},
	],
	widgets: [
		{
			key: "w1",
			type: "kpis",
		},
		{
			key: "w2",
			params: {
				sla_sec: 20,
			},
			type: "queues",
		},
	],
});
console.log(report);
```

## `delete()`

**Delete a report.** Deletes the report, its runs and their stored files. Needs a live key.

```ts
mv.reports.delete(id: ReportsDeleteData["path"]["id"], options?: RequestOptions): Promise<ReportsDeleteResponse>
```

`DELETE /reports/{id}` · [API reference](https://docs.morevoice.ai/api/operations/reports_delete/)

### Parameters

| Name | Type | Required | Description |
| --- | --- | --- | --- |
| `id` | `string` | yes | A report ID (`rpt_…`). |
| `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.headers["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. |
| `options` | `RequestOptions` | no | `idempotencyKey`, extra `headers` and an abort `signal`: see [retries and idempotency](https://docs.morevoice.ai/sdk/typescript/retries/). |

### Returns

`DeletedReport`:

| Field | Type | Description |
| --- | --- | --- |
| `object` | `"report"` | Always `report`. |
| `id` | `string` | A report ID (prefix `rpt_`). |
| `deleted` | `true` | — |

### Example

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

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

const deletedReport = await mv.reports.delete("rpt_7Hk2Lm9Qp");
console.log(deletedReport);
```

## `downloadRunCsv()`

**Download a run's CSV.** The CSV stored for a run (404 when the report has no CSV format, or no storage bucket is configured). Needs a live key.

```ts
mv.reports.downloadRunCsv(id: ReportsDownloadRunCsvData["path"]["id"], options?: RequestOptions): Promise<ReportsDownloadRunCsvResponse>
```

`GET /report_runs/{id}/csv` · [API reference](https://docs.morevoice.ai/api/operations/reports_download_run_csv/)

### Parameters

| Name | Type | Required | Description |
| --- | --- | --- | --- |
| `id` | `string` | yes | A report run ID (`rptrun_…`). |
| `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

Nothing, on success.

### Example

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

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

const data = await mv.reports.downloadRunCsv("rptrun_7Hk2Lm9Qp");
console.log(data);
```

## `downloadRunPdf()`

**Download a run's PDF.** The PDF stored for a run (404 when the report has no PDF format, or no storage bucket is configured). Needs a live key.

```ts
mv.reports.downloadRunPdf(id: ReportsDownloadRunPdfData["path"]["id"], options?: RequestOptions): Promise<ReportsDownloadRunPdfResponse>
```

`GET /report_runs/{id}/pdf` · [API reference](https://docs.morevoice.ai/api/operations/reports_download_run_pdf/)

### Parameters

| Name | Type | Required | Description |
| --- | --- | --- | --- |
| `id` | `string` | yes | A report run ID (`rptrun_…`). |
| `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

Nothing, on success.

### Example

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

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

const data = await mv.reports.downloadRunPdf("rptrun_7Hk2Lm9Qp");
console.log(data);
```

## `list()`

**List reports.** Returns a page of `Report` objects, newest first. Pass `next_cursor` as `starting_after` for the next page; the SDKs iterate every page for you.

```ts
mv.reports.list(query?: NonNullable<ReportsListData["query"]>, options?: RequestOptions): PagedList<ReportsListResponse["data"][number], NonNullable<ReportsListData["query"]>>
```

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

### Parameters

| Name | Type | Required | Description |
| --- | --- | --- | --- |
| `query.limit` | `integer` | no | How many objects to return, 1–100 (default 20). |
| `query.starting_after` | `string` | no | A cursor (`next_cursor`) or object ID: return the objects after it (older). |
| `query.ending_before` | `string` | no | A cursor or object ID: return the objects before it (newer). |
| `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

A [`PagedList`](https://docs.morevoice.ai/sdk/typescript/pagination/): `await` it for the first page, `for await` it for every item.

### Example

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

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

for await (const report of mv.reports.list()) {
	console.log(report);
}
```

## `listRuns()`

**List a report's runs.** Returns a page of `ReportRun` objects, newest first. Pass `next_cursor` as `starting_after` for the next page; the SDKs iterate every page for you. Answers `404` with the code `resource_missing` when nothing has this ID in this organisation and mode.

```ts
mv.reports.listRuns(id: ReportsListRunsData["path"]["id"], query?: NonNullable<ReportsListRunsData["query"]>, options?: RequestOptions): PagedList<ReportsListRunsResponse["data"][number], NonNullable<ReportsListRunsData["query"]>>
```

`GET /reports/{id}/runs` · [API reference](https://docs.morevoice.ai/api/operations/reports_list_runs/)

### Parameters

| Name | Type | Required | Description |
| --- | --- | --- | --- |
| `id` | `string` | yes | A report ID (`rpt_…`). |
| `query.limit` | `integer` | no | How many objects to return, 1–100 (default 20). |
| `query.starting_after` | `string` | no | A cursor (`next_cursor`) or object ID: return the objects after it (older). |
| `query.ending_before` | `string` | no | A cursor or object ID: return the objects before it (newer). |
| `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

A [`PagedList`](https://docs.morevoice.ai/sdk/typescript/pagination/): `await` it for the first page, `for await` it for every item.

### Example

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

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

for await (const report of mv.reports.listRuns("rpt_7Hk2Lm9Qp")) {
	console.log(report);
}
```

## `preview()`

**Preview report data.** 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.

```ts
mv.reports.preview(body: ReportsPreviewData["body"], options?: RequestOptions): Promise<ReportsPreviewResponse>
```

`POST /reports/preview` · [API reference](https://docs.morevoice.ai/api/operations/reports_preview/)

### Parameters

| Name | Type | Required | Description |
| --- | --- | --- | --- |
| `body.widgets` | `object[]` | yes |  |
| `body.cadence` | `object` | no | A cadence to list the next three send times for. |
| `body.filters` | `object` | no |  |
| `body.language` | `"he" \| "en"` | no | The language of labels in the result (default en). |
| `body.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. |
| `body.timezone` | `string` | no | Default Asia/Jerusalem. |
| `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.headers["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. |
| `options` | `RequestOptions` | no | `idempotencyKey`, extra `headers` and an abort `signal`: see [retries and idempotency](https://docs.morevoice.ai/sdk/typescript/retries/). |

### Returns

`ReportPreview`:

| Field | Type | Description |
| --- | --- | --- |
| `object` | `"report_preview"` | Always `report_preview`. |
| `livemode` | `boolean` | `true` in live mode, `false` in test mode. |
| `period` | `object` | — |
| `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

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

## `retrieve()`

**Retrieve a report.** Returns the `Report` object. Answers `404` with the code `resource_missing` when nothing has this ID in this organisation and mode.

```ts
mv.reports.retrieve(id: ReportsRetrieveData["path"]["id"], options?: RequestOptions): Promise<ReportsRetrieveResponse>
```

`GET /reports/{id}` · [API reference](https://docs.morevoice.ai/api/operations/reports_retrieve/)

### Parameters

| Name | Type | Required | Description |
| --- | --- | --- | --- |
| `id` | `string` | yes | A report ID (`rpt_…`). |
| `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

`Report`:

| Field | Type | Description |
| --- | --- | --- |
| `object` | `"report"` | Always `report`. |
| `id` | `string` | A report ID (prefix `rpt_`). |
| `livemode` | `boolean` | `true` in live mode, `false` in test mode. |
| `name` | `string` | — |
| `enabled` | `boolean` | Disabled reports are not sent on their schedule (they can still be sent now). |
| `widgets` | `object[]` | — |
| `period` | `"today" \| "yesterday" \| "last7" \| "last30" \| "thisWeek" \| "lastWeek" \| "thisMonth" \| "lastMonth"` | The window each report covers, in its time zone: `today`, `yesterday`, `last7`, `last30`, `thisWeek`, `lastWeek`, `thisMonth` or `lastMonth`. |
| `filters` | `object` | — |
| `cadence` | `object` | — |
| `recipients` | `object[]` | — |
| `formats` | `object` | — |
| `language` | `"he" \| "en"` | — |
| `owner_id` | `string \| null` | `usr_…` ID. |
| `next_run_at` | `string \| null` | — |
| `last_run_at` | `string \| null` | — |
| `last_run` | `object \| null` | The latest run (list responses only; null on others). |
| `created` | `string` | An ISO-8601 timestamp in UTC. |
| `updated` | `string` | An ISO-8601 timestamp in UTC. |

### Example

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

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

const report = await mv.reports.retrieve("rpt_7Hk2Lm9Qp");
console.log(report);
```

## `send()`

**Send a report now.** Computes the report for its period, stores the files and emails every recipient; returns the run when it finished. Send an Idempotency-Key: a retry with the same key returns the same run instead of emailing again. A second send of the same report while one is in progress is a 409. Needs a live key.

```ts
mv.reports.send(id: ReportsSendData["path"]["id"], body?: ReportsSendData["body"], options?: RequestOptions): Promise<ReportsSendResponse>
```

`POST /reports/{id}/send` · [API reference](https://docs.morevoice.ai/api/operations/reports_send/)

### Parameters

| Name | Type | Required | Description |
| --- | --- | --- | --- |
| `id` | `string` | yes | A report ID (`rpt_…`). |
| `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.headers["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. |
| `options` | `RequestOptions` | no | `idempotencyKey`, extra `headers` and an abort `signal`: see [retries and idempotency](https://docs.morevoice.ai/sdk/typescript/retries/). |

### Returns

`ReportRun`:

| Field | Type | Description |
| --- | --- | --- |
| `object` | `"report_run"` | Always `report_run`. |
| `id` | `string` | A report run ID (prefix `rptrun_`). |
| `livemode` | `boolean` | `true` in live mode, `false` in test mode. |
| `report_id` | `string` | A report ID (prefix `rpt_`). |
| `trigger` | `string` | `scheduled`, `manual` (sent now) or `test`. |
| `status` | `string` | `running`, `sent`, `partial` (some recipients or the PDF failed) or `failed`. |
| `period_from` | `string \| null` | — |
| `period_to` | `string \| null` | — |
| `recipients` | `string[]` | — |
| `deliveries` | `object[]` | — |
| `artifacts` | `object` | Stored files you can download (GET /v1/report_runs/{id}/pdf\|csv). |
| `error` | `string \| null` | — |
| `started_at` | `string` | An ISO-8601 timestamp in UTC. |
| `finished_at` | `string \| null` | — |

### Example

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

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

const reportRun = await mv.reports.send("rpt_7Hk2Lm9Qp", {});
console.log(reportRun);
```

## `update()`

**Update a report.** Only the fields you send change (`filters`, `recipients`, `widgets` and `cadence` are replaced as a whole). Needs a live key.

```ts
mv.reports.update(id: ReportsUpdateData["path"]["id"], body?: ReportsUpdateData["body"], options?: RequestOptions): Promise<ReportsUpdateResponse>
```

`PATCH /reports/{id}` · [API reference](https://docs.morevoice.ai/api/operations/reports_update/)

### Parameters

| Name | Type | Required | Description |
| --- | --- | --- | --- |
| `id` | `string` | yes | A report ID (`rpt_…`). |
| `body.cadence` | `object` | no |  |
| `body.enabled` | `boolean` | no |  |
| `body.filters` | `object` | no |  |
| `body.formats` | `object` | no | Default: email and PDF. |
| `body.language` | `"he" \| "en"` | no | Default he. |
| `body.name` | `string` | no |  |
| `body.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. |
| `body.recipients` | `object[]` | no |  |
| `body.widgets` | `object[]` | no |  |
| `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

`Report`:

| Field | Type | Description |
| --- | --- | --- |
| `object` | `"report"` | Always `report`. |
| `id` | `string` | A report ID (prefix `rpt_`). |
| `livemode` | `boolean` | `true` in live mode, `false` in test mode. |
| `name` | `string` | — |
| `enabled` | `boolean` | Disabled reports are not sent on their schedule (they can still be sent now). |
| `widgets` | `object[]` | — |
| `period` | `"today" \| "yesterday" \| "last7" \| "last30" \| "thisWeek" \| "lastWeek" \| "thisMonth" \| "lastMonth"` | The window each report covers, in its time zone: `today`, `yesterday`, `last7`, `last30`, `thisWeek`, `lastWeek`, `thisMonth` or `lastMonth`. |
| `filters` | `object` | — |
| `cadence` | `object` | — |
| `recipients` | `object[]` | — |
| `formats` | `object` | — |
| `language` | `"he" \| "en"` | — |
| `owner_id` | `string \| null` | `usr_…` ID. |
| `next_run_at` | `string \| null` | — |
| `last_run_at` | `string \| null` | — |
| `last_run` | `object \| null` | The latest run (list responses only; null on others). |
| `created` | `string` | An ISO-8601 timestamp in UTC. |
| `updated` | `string` | An ISO-8601 timestamp in UTC. |

### Example

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

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

const report = await mv.reports.update("rpt_7Hk2Lm9Qp", {
	enabled: false,
});
console.log(report);
```