client.usage

Metered usage. These methods are on client.usage, where client is a MoreVoice client (see the Python SDK). 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).

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

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

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)