# client.usage

> The usage methods of the morevoice Python SDK: Metered usage.

Metered usage. These methods are on `client.usage`, 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.

## `retrieve()`

**Retrieve usage.** Usage per day or month and kind, with its price from your price book (minor units of your billing currency). `totals` sums the range per kind: for a calendar month they are the billing page's figures. Test keys get their test-mode usage, which is never billed (amounts are null).

```python
# client.usage
def retrieve(self, *, from_: str, to: str, granularity: _m.UsageRetrieveGranularity | Unset = "day", group_by: _m.UsageRetrieveGroupBy | Unset = "kind", kind: _m.UsageRetrieveKind | Unset = UNSET, more_voice_version: str | Unset = UNSET) -> _m.UsageReport
```

`client.usage.retrieve()` · `await async_client.usage.retrieve()` · `GET /usage` · [API reference](https://docs.morevoice.ai/api/operations/usage_retrieve/)

### Parameters

| Name | Type | Required | Description |
| --- | --- | --- | --- |
| `from` | `string` | yes | The first day (YYYY-MM-DD, the organisation's time zone). |
| `to` | `string` | yes | The last day, inclusive. Per kind: up to 400 days; per assistant or campaign (and in test mode): up to 92 days. |
| `granularity` | `"day" \| "month"` | no | One row per day (default) or per calendar month. |
| `group_by` | `"kind" \| "assistant" \| "campaign"` | no | `kind` (default): one row per period and usage kind; `assistant` / `campaign`: also split by the assistant or campaign the usage belongs to. |
| `kind` | `"ai_minute" \| "pbx_minute" \| "carrier_minute" \| "copilot_minute" \| "seat_day" \| "copilot_seat_day" \| "qa_scored_call" \| "kb_storage_gb_day" \| …` | no | Only this usage kind. |

### Returns

`UsageReport`:

| Field | Type | Description |
| --- | --- | --- |
| `object` | `"usage_report"` | Always `usage_report`. |
| `livemode` | `boolean` | `true` in live mode, `false` in test mode. |
| `from` | `string` | — |
| `to` | `string` | — |
| `timezone` | `string` | The organisation's time zone: the days and months are its local calendar. |
| `granularity` | `"day" \| "month"` | — |
| `group_by` | `"kind" \| "assistant" \| "campaign"` | — |
| `data` | `object[]` | — |
| `totals` | `object[]` | The whole range per kind: for a calendar month, the figures of the billing page's usage summary. |
| `total` | `Money \| null` | The whole range's price; null when nothing was priced. |

### Example

```python
from morevoice import MoreVoice

client = MoreVoice()  # MOREVOICE_API_KEY from the environment

usage_report = client.usage.retrieve(from_="2026-10-01", to="2026-10-31")
print(usage_report)
```