# mv.usage

> The usage methods of @morevoice/sdk: Metered usage.

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

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

```ts
mv.usage.retrieve(query: NonNullable<UsageRetrieveData["query"]>, options?: RequestOptions): Promise<UsageRetrieveResponse>
```

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

### Parameters

| Name | Type | Required | Description |
| --- | --- | --- | --- |
| `query.from` | `string` | yes | The first day (YYYY-MM-DD, the organisation's time zone). |
| `query.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. |
| `query.granularity` | `string` | no | One row per day (default) or per calendar month. |
| `query.group_by` | `string` | no | `kind` (default): one row per period and usage kind; `assistant` / `campaign`: also split by the assistant or campaign the usage belongs to. |
| `query.kind` | `string` | no | Only this usage kind. |
| `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

`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

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

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

const usageReport = await mv.usage.retrieve({
	from: "2026-10-01",
	to: "2026-10-31",
});
console.log(usageReport);
```