mv.usage

Metered usage. These methods are on mv.usage, where mv is your client (see the Node.js SDK). 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).

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

GET /usage · API reference

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.

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

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