Skip to content
MoreVoiceDevelopers

Retrieve usage

GET
/usage
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);

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

Try it in the API playground with a test-mode key.

Authorizations

Section titled “Authorizations”

Parameters

Section titled “Parameters”

Query Parameters

Section titled “Query Parameters”
from
required
string
/^\d{4}-\d{2}-\d{2}$/

The first day (YYYY-MM-DD, the organisation’s time zone).

to
required
string
/^\d{4}-\d{2}-\d{2}$/

The last day, inclusive. Per kind: up to 400 days; per assistant or campaign (and in test mode): up to 92 days.

granularity
string
default: day
Allowed values: day month

One row per day (default) or per calendar month.

group_by
string
default: kind
Allowed values: kind assistant campaign

kind (default): one row per period and usage kind; assistant / campaign: also split by the assistant or campaign the usage belongs to.

kind
string
Allowed values: ai_minute pbx_minute carrier_minute copilot_minute seat_day copilot_seat_day qa_scored_call kb_storage_gb_day recording_storage_gb_day sms email did_month api_request platform_ai_usd did_setup

Only this usage kind.

Header Parameters

Section titled “Header Parameters”
MoreVoice-Version
string
/^\d{4}-\d{2}-\d{2}$/

The API version to use for this request. Defaults to the version the API key is pinned to.

Example
2026-11-01

Responses

Section titled “Responses”

200

Section titled “200”

OK

Media typeapplication/json

Metered usage and its price for a date range.

object
data
required
Array<object>
object
amount
required
Any of:

An amount of money in minor units.

object
amount
required

The amount in the currency’s minor unit (agorot, cents).

integer
>= -9007199254740991 <= 9007199254740991
currency
required

ISO 4217 currency code.

string
Allowed values: ILS USD EUR
assistant_id
Any of:

Group_by assistant: the assistant, or null for usage without one.

string
/^asst_[0-9A-Za-z]+$/
campaign_id
Any of:

Group_by campaign: the campaign, or null for usage without one.

string
/^cmp_[0-9A-Za-z]+$/
events
required

Metered events behind the row.

integer
>= -9007199254740991 <= 9007199254740991
kind
required

The usage kind, e.g. ai_minute, pbx_minute, carrier_minute, seat_day, qa_scored_call, sms, api_request.

string
period
required

YYYY-MM-DD (granularity day) or YYYY-MM (month), in the organisation’s time zone.

string
quantity
required

In units (minutes are decimals).

number
unit
required

Minute, seat_day, call, gb_day, message, number_month, number, request or usd.

string
from
required
string
granularity
required
string
Allowed values: day month
group_by
required
string
Allowed values: kind assistant campaign
livemode
required

true in live mode, false in test mode.

boolean
object
required
string
Allowed value: usage_report
timezone
required

The organisation’s time zone: the days and months are its local calendar.

string
to
required
string
total
required
Any of:

An amount of money in minor units.

object
amount
required

The amount in the currency’s minor unit (agorot, cents).

integer
>= -9007199254740991 <= 9007199254740991
currency
required

ISO 4217 currency code.

string
Allowed values: ILS USD EUR
totals
required

The whole range per kind: for a calendar month, the figures of the billing page’s usage summary.

Array<object>
object
amount
required
Any of:

An amount of money in minor units.

object
amount
required

The amount in the currency’s minor unit (agorot, cents).

integer
>= -9007199254740991 <= 9007199254740991
currency
required

ISO 4217 currency code.

string
Allowed values: ILS USD EUR
kind
required
string
quantity
required
number
unit
required
string
Example
{
  "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

Section titled “400”

The request is invalid: a parameter is missing, malformed or unknown, or the version header is unknown.

Media typeapplication/json

Every /v1 error.

object
error
required
object
code
required

A stable, machine-readable code from the error-code catalogue.

string
details

Structured context, e.g. required_scope or the compliance verdict.

object
key
additional properties
doc_url
required

A link to the documentation of this code.

string
message
required

A human-readable explanation. Do not parse it.

string
param

The request parameter the error relates to, e.g. to or metadata[order_id].

string
request_id
required

The X-Request-Id of this request. Quote it when you contact support.

string
type
required

The category of the error.

string
Allowed values: invalid_request_error authentication_error permission_error not_found conflict rate_limit_error compliance_error idempotency_error api_error
Example
{
  "error": {
    "code": "parameter_missing",
    "doc_url": "https://docs.morevoice.ai/api/errors#parameter-missing",
    "message": "Missing required parameter: to.",
    "param": "to",
    "request_id": "req_7Hk2LmN9pQ4rS6tV8wX0yZ",
    "type": "invalid_request_error"
  }
}

Headers

Section titled “Headers”
X-Request-Id
string

The request’s ID (req_…). Quote it when you contact support.

401

Section titled “401”

No valid API key was sent.

Media typeapplication/json

Every /v1 error.

object
error
required
object
code
required

A stable, machine-readable code from the error-code catalogue.

string
details

Structured context, e.g. required_scope or the compliance verdict.

object
key
additional properties
doc_url
required

A link to the documentation of this code.

string
message
required

A human-readable explanation. Do not parse it.

string
param

The request parameter the error relates to, e.g. to or metadata[order_id].

string
request_id
required

The X-Request-Id of this request. Quote it when you contact support.

string
type
required

The category of the error.

string
Allowed values: invalid_request_error authentication_error permission_error not_found conflict rate_limit_error compliance_error idempotency_error api_error
Example
{
  "error": {
    "code": "invalid_api_key",
    "doc_url": "https://docs.morevoice.ai/api/errors#invalid-api-key",
    "message": "Invalid API key.",
    "request_id": "req_7Hk2LmN9pQ4rS6tV8wX0yZ",
    "type": "authentication_error"
  }
}

Headers

Section titled “Headers”
X-Request-Id
string

The request’s ID (req_…). Quote it when you contact support.

403

Section titled “403”

The key may not do this (a missing scope, a plan limit, or a compliance block).

Media typeapplication/json

Every /v1 error.

object
error
required
object
code
required

A stable, machine-readable code from the error-code catalogue.

string
details

Structured context, e.g. required_scope or the compliance verdict.

object
key
additional properties
doc_url
required

A link to the documentation of this code.

string
message
required

A human-readable explanation. Do not parse it.

string
param

The request parameter the error relates to, e.g. to or metadata[order_id].

string
request_id
required

The X-Request-Id of this request. Quote it when you contact support.

string
type
required

The category of the error.

string
Allowed values: invalid_request_error authentication_error permission_error not_found conflict rate_limit_error compliance_error idempotency_error api_error
Example
{
  "error": {
    "code": "missing_scope",
    "doc_url": "https://docs.morevoice.ai/api/errors#missing-scope",
    "message": "This API key lacks the calls:write scope.",
    "request_id": "req_7Hk2LmN9pQ4rS6tV8wX0yZ",
    "type": "permission_error"
  }
}

Headers

Section titled “Headers”
X-Request-Id
string

The request’s ID (req_…). Quote it when you contact support.

429

Section titled “429”

Too many requests, or no call capacity right now. Retry after the Retry-After delay.

Media typeapplication/json

Every /v1 error.

object
error
required
object
code
required

A stable, machine-readable code from the error-code catalogue.

string
details

Structured context, e.g. required_scope or the compliance verdict.

object
key
additional properties
doc_url
required

A link to the documentation of this code.

string
message
required

A human-readable explanation. Do not parse it.

string
param

The request parameter the error relates to, e.g. to or metadata[order_id].

string
request_id
required

The X-Request-Id of this request. Quote it when you contact support.

string
type
required

The category of the error.

string
Allowed values: invalid_request_error authentication_error permission_error not_found conflict rate_limit_error compliance_error idempotency_error api_error
Example
{
  "error": {
    "code": "rate_limited",
    "doc_url": "https://docs.morevoice.ai/api/errors#rate-limited",
    "message": "Too many requests. Retry after 1 second.",
    "request_id": "req_7Hk2LmN9pQ4rS6tV8wX0yZ",
    "type": "rate_limit_error"
  }
}

Headers

Section titled “Headers”
Retry-After
integer

Seconds to wait before retrying.

X-Request-Id
string

The request’s ID (req_…). Quote it when you contact support.

500

Section titled “500”

Something went wrong on MoreVoice’s side. Retry with the same Idempotency-Key.

Media typeapplication/json

Every /v1 error.

object
error
required
object
code
required

A stable, machine-readable code from the error-code catalogue.

string
details

Structured context, e.g. required_scope or the compliance verdict.

object
key
additional properties
doc_url
required

A link to the documentation of this code.

string
message
required

A human-readable explanation. Do not parse it.

string
param

The request parameter the error relates to, e.g. to or metadata[order_id].

string
request_id
required

The X-Request-Id of this request. Quote it when you contact support.

string
type
required

The category of the error.

string
Allowed values: invalid_request_error authentication_error permission_error not_found conflict rate_limit_error compliance_error idempotency_error api_error
Example
{
  "error": {
    "code": "internal_error",
    "doc_url": "https://docs.morevoice.ai/api/errors#internal-error",
    "message": "Something went wrong on MoreVoice's side.",
    "request_id": "req_7Hk2LmN9pQ4rS6tV8wX0yZ",
    "type": "api_error"
  }
}

Headers

Section titled “Headers”
X-Request-Id
string

The request’s ID (req_…). Quote it when you contact support.