# client.reports

> The reports methods of the morevoice Python SDK: Scheduled reports, previews and runs.

Scheduled reports, previews and runs. These methods are on `client.reports`, where `client` is a `MoreVoice` client (see [the Python SDK](https://docs.morevoice.ai/sdk/python/#connect)). On `AsyncMoreVoice` the same methods are awaited. Each one returns the response object and raises an exception 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.

```python
# client.reports
def catalog(self, *, language: _m.ReportsCatalogLanguage | Unset = "en", more_voice_version: str | Unset = UNSET) -> _m.ReportCatalog
```

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

### Parameters

| Name | Type | Required | Description |
| --- | --- | --- | --- |
| `language` | `"he" \| "en"` | no | The language of names and descriptions (default en). |

### 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

```python
from morevoice import MoreVoice

client = MoreVoice()  # MOREVOICE_API_KEY from the environment

report_catalog = client.reports.catalog()
print(report_catalog)
```

## `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.

```python
# client.reports
def create(self, body: _m.ReportsCreateBody | Mapping[str, Any], *, more_voice_version: str | Unset = UNSET, idempotency_key: str | Unset = UNSET) -> _m.Report
```

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

### Request body

| Field | Type | Required | Description |
| --- | --- | --- | --- |
| `name` | `string` | yes | — |
| `widgets` | `object[]` | yes | — |
| `cadence` | `object` | yes | — |
| `enabled` | `boolean` | no | — |
| `filters` | `object` | no | — |
| `formats` | `object` | no | Default: email and PDF. |
| `language` | `"he" \| "en"` | no | Default he. |
| `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. |
| `recipients` | `object[]` | no | — |

### 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

```python
from morevoice import MoreVoice

client = MoreVoice()  # MOREVOICE_API_KEY from the environment

report = client.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",
        },
    ],
})
print(report)
```

## `delete()`

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

```python
# client.reports
def delete(self, id: str, *, more_voice_version: str | Unset = UNSET, idempotency_key: str | Unset = UNSET) -> _m.DeletedReport
```

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

### Parameters

| Name | Type | Required | Description |
| --- | --- | --- | --- |
| `id` | `str` | yes | A report ID (`rpt_…`). |

### Returns

`DeletedReport`:

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

### Example

```python
from morevoice import MoreVoice

client = MoreVoice()  # MOREVOICE_API_KEY from the environment

deleted_report = client.reports.delete("rpt_7Hk2Lm9Qp")
print(deleted_report)
```

## `download_run_csv()`

**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.

```python
# client.reports
def download_run_csv(self, id: str, *, more_voice_version: str | Unset = UNSET) -> str
```

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

### Parameters

| Name | Type | Required | Description |
| --- | --- | --- | --- |
| `id` | `str` | yes | A report run ID (`rptrun_…`). |

### Returns

Nothing, on success.

### Example

```python
from morevoice import MoreVoice

client = MoreVoice()  # MOREVOICE_API_KEY from the environment

data = client.reports.download_run_csv("rptrun_7Hk2Lm9Qp")
print(data)
```

## `download_run_pdf()`

**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.

```python
# client.reports
def download_run_pdf(self, id: str, *, more_voice_version: str | Unset = UNSET) -> bytes
```

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

### Parameters

| Name | Type | Required | Description |
| --- | --- | --- | --- |
| `id` | `str` | yes | A report run ID (`rptrun_…`). |

### Returns

Nothing, on success.

### Example

```python
from morevoice import MoreVoice

client = MoreVoice()  # MOREVOICE_API_KEY from the environment

data = client.reports.download_run_pdf("rptrun_7Hk2Lm9Qp")
print(len(data), "bytes")
```

## `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.

```python
# client.reports
def list(self, *, limit: int | Unset = 20, starting_after: str | Unset = UNSET, ending_before: str | Unset = UNSET, more_voice_version: str | Unset = UNSET) -> AsyncPage[_m.Report]
```

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

### Parameters

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

### Returns

A page of results (`ReportList`): `data`, `has_more` and `next_cursor`.

### Example

```python
from morevoice import MoreVoice

client = MoreVoice()  # MOREVOICE_API_KEY from the environment

for report in client.reports.list():
    print(report)
```

## `list_runs()`

**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.

```python
# client.reports
def list_runs(self, id: str, *, limit: int | Unset = 20, starting_after: str | Unset = UNSET, ending_before: str | Unset = UNSET, more_voice_version: str | Unset = UNSET) -> AsyncPage[_m.ReportRun]
```

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

### Parameters

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

### Returns

A page of results (`ReportRunList`): `data`, `has_more` and `next_cursor`.

### Example

```python
from morevoice import MoreVoice

client = MoreVoice()  # MOREVOICE_API_KEY from the environment

for report in client.reports.list_runs("rpt_7Hk2Lm9Qp"):
    print(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.

```python
# client.reports
def preview(self, body: _m.ReportsPreviewBody | Mapping[str, Any], *, more_voice_version: str | Unset = UNSET, idempotency_key: str | Unset = UNSET) -> _m.ReportPreview
```

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

### Request body

| Field | Type | Required | Description |
| --- | --- | --- | --- |
| `widgets` | `object[]` | yes | — |
| `cadence` | `object` | no | A cadence to list the next three send times for. |
| `filters` | `object` | 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. |

### 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

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

## `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.

```python
# client.reports
def retrieve(self, id: str, *, more_voice_version: str | Unset = UNSET) -> _m.Report
```

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

### Parameters

| Name | Type | Required | Description |
| --- | --- | --- | --- |
| `id` | `str` | yes | A report ID (`rpt_…`). |

### 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

```python
from morevoice import MoreVoice

client = MoreVoice()  # MOREVOICE_API_KEY from the environment

report = client.reports.retrieve("rpt_7Hk2Lm9Qp")
print(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.

```python
# client.reports
def send(self, id: str, body: _m.ReportSendParamsInput | Mapping[str, Any] | Unset = UNSET, *, more_voice_version: str | Unset = UNSET, idempotency_key: str | Unset = UNSET) -> _m.ReportRun
```

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

### Parameters

| Name | Type | Required | Description |
| --- | --- | --- | --- |
| `id` | `str` | yes | A report ID (`rpt_…`). |

### 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

```python
from morevoice import MoreVoice

client = MoreVoice()  # MOREVOICE_API_KEY from the environment

report_run = client.reports.send("rpt_7Hk2Lm9Qp", {})
print(report_run)
```

## `update()`

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

```python
# client.reports
def update(self, id: str, body: _m.ReportsUpdateBody | Mapping[str, Any] | Unset = UNSET, *, more_voice_version: str | Unset = UNSET) -> _m.Report
```

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

### Parameters

| Name | Type | Required | Description |
| --- | --- | --- | --- |
| `id` | `str` | yes | A report ID (`rpt_…`). |

### Request body

| Field | Type | Required | Description |
| --- | --- | --- | --- |
| `cadence` | `object` | no | — |
| `enabled` | `boolean` | no | — |
| `filters` | `object` | no | — |
| `formats` | `object` | no | Default: email and PDF. |
| `language` | `"he" \| "en"` | no | Default he. |
| `name` | `string` | no | — |
| `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. |
| `recipients` | `object[]` | no | — |
| `widgets` | `object[]` | no | — |

### 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

```python
from morevoice import MoreVoice

client = MoreVoice()  # MOREVOICE_API_KEY from the environment

report = client.reports.update("rpt_7Hk2Lm9Qp", {
    "enabled": False,
})
print(report)
```