# Retrieve usage

`GET https://api.morevoice.ai/v1/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).

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

Operation ID: `usage_retrieve`.

## Parameters

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

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

## Responses

### 200 OK

OK Returns `UsageReport`.

| Field | Type | Description |
| --- | --- | --- |
| `object` | `"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. |
| `total.amount` | `integer` | The amount in the currency's minor unit (agorot, cents). |
| `total.currency` | `"ILS" \| "USD" \| "EUR"` | ISO 4217 currency code. |

Example:

```json
{
  "data": [
    {
      "amount": {
        "amount": 41250,
        "currency": "ILS"
      },
      "events": 268,
      "kind": "ai_minute",
      "period": "2026-11-03",
      "quantity": 412.5,
      "unit": "minute"
    }
  ],
  "from": "2026-11-01",
  "granularity": "day",
  "group_by": "kind",
  "livemode": true,
  "object": "usage_report",
  "timezone": "Asia/Jerusalem",
  "to": "2026-11-30",
  "total": {
    "amount": 41250,
    "currency": "ILS"
  },
  "totals": [
    {
      "amount": {
        "amount": 41250,
        "currency": "ILS"
      },
      "kind": "ai_minute",
      "quantity": 412.5,
      "unit": "minute"
    }
  ]
}
```

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

### 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 usageReport = await mv.usage.retrieve({
	from: "2026-10-01",
	to: "2026-10-31",
});
console.log(usageReport);
```

**Python**

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

**cURL**

```sh
curl -G https://api.morevoice.ai/v1/usage \
  -H "Authorization: Bearer $MOREVOICE_API_KEY" \
  --data-urlencode 'from=2026-10-01' \
  --data-urlencode 'to=2026-10-31'
```