Subscription Usage

Get subscription usage.

Get subscription usage

GET/subscriptions/{subscriptionId}/usage

Retrieve the current period's usage for a subscription.

Path parameters

subscriptionIdstringrequired

The identifier of the subscription. May be the entity's internal UUID or an external reference identifier. Reference identifiers MUST be prefixed with rid_ (e.g., rid_crm-subscription-12345) so the API can distinguish them from internal UUIDs. The prefix is stripped before lookup.

Responses

200

Current usage statistics for the subscription.

application/json

Current usage statistics for the subscription.

objectUsage

Current usage statistics for a subscription, organized by service type (voice, SMS, MMS, data). Within each service type, usage is broken down into per-package allowance buckets: the base plan's included allowance plus any add-on packages, each reporting used, remaining, and total amounts. A service type is omitted entirely when the subscription has no allowances of that type.

voiceobject

Voice call usage across all scopes and packages.

Voice call usage for a subscription, split by where and to whom calls are made: national (domestic calls), roaming (calls made while abroad), and ILD (international long distance — calls placed from the home country to foreign numbers).

Show child attributes

nationalarray of UsageVoicePackage

Allowance buckets for calls made within the home country, including the base plan's voice allowance and any add-on packages.

Show child attributes

subscriptionAddonIdstring

The subscription add-on that granted this allowance. Present only when the package comes from an add-on; absent for the base plan's included allowance.

namestringrequired

Human-readable name of the package, as shown to end users.

callSecondsintegerint64required

Call time consumed from this allowance so far, in seconds.

callCountintegerint64required

Number of calls placed against this allowance.

callRemainingSecondsintegerint64required

Call time still available in this allowance, in seconds.

callTotalSecondsintegerint64required

The full call time allowance of this package, in seconds.

statusenum<string>required

The status of this package.

Whether a usage package is currently consumable.

ACTIVE: The package is in its validity window and usage draws from it
NOT_ACTIVE: The package exists but is not currently consumable, for example a purchased package whose validity window has not started yet
EXPIRED: The package's validity window has ended; any remaining allowance is no longer usable

values

ACTIVE
NOT_ACTIVE
EXPIRED

validFromstringdate-time

Start of the period this allowance applies to.

validTostringdate-time

End of the period this allowance applies to. For base plan allowances this is the end of the current billing period (when the allowance resets); for time-limited add-on packages it is when the package itself expires.

metadataobject with string keys

A set of key-value pairs that can be attached to an object for storing additional information in a semi-structured format. Provided by API clients and returned as-is; the platform does not interpret the values.

Show child attributes

roamingarray of UsageVoicePackage

Allowance buckets for calls made while roaming abroad.

Show child attributes

subscriptionAddonIdstring

The subscription add-on that granted this allowance. Present only when the package comes from an add-on; absent for the base plan's included allowance.

namestringrequired

Human-readable name of the package, as shown to end users.

callSecondsintegerint64required

Call time consumed from this allowance so far, in seconds.

callCountintegerint64required

Number of calls placed against this allowance.

callRemainingSecondsintegerint64required

Call time still available in this allowance, in seconds.

callTotalSecondsintegerint64required

The full call time allowance of this package, in seconds.

statusenum<string>required

The status of this package.

Whether a usage package is currently consumable.

ACTIVE: The package is in its validity window and usage draws from it
NOT_ACTIVE: The package exists but is not currently consumable, for example a purchased package whose validity window has not started yet
EXPIRED: The package's validity window has ended; any remaining allowance is no longer usable

values

ACTIVE
NOT_ACTIVE
EXPIRED

validFromstringdate-time

Start of the period this allowance applies to.

validTostringdate-time

End of the period this allowance applies to. For base plan allowances this is the end of the current billing period (when the allowance resets); for time-limited add-on packages it is when the package itself expires.

metadataobject with string keys

A set of key-value pairs that can be attached to an object for storing additional information in a semi-structured format. Provided by API clients and returned as-is; the platform does not interpret the values.

Show child attributes

ildarray of UsageVoiceIldPackage

International long distance (ILD) balances for calls placed from the home country to foreign numbers. Tracked as a monetary balance rather than minutes.

Show child attributes

subscriptionAddonIdstring

The subscription add-on that granted this balance. Present only when the balance comes from an add-on.

namestringrequired

Human-readable name of the package, as shown to end users.

balanceMinorintegerint64

Remaining prepaid amount available for international long distance calls, in minor units of the currency given by currency. Each ILD call deducts from this balance at the destination's per-minute rate.

currencystring

Three-letter ISO 4217 code for the currency the balance is denominated in. Matches the subscription's billing currency.

expiryDatestringdate

The date the remaining balance expires and can no longer be used. Absent when the balance does not expire.

metadataobject with string keys

A set of key-value pairs that can be attached to an object for storing additional information in a semi-structured format. Provided by API clients and returned as-is; the platform does not interpret the values.

Show child attributes

smsobject

SMS usage across all scopes and packages.

SMS usage for a subscription, split by where and to whom messages are sent: national (domestic messages), roaming (messages sent while abroad), and ILD (international long distance — messages sent from the home country to foreign numbers).

Show child attributes

nationalarray of UsageSmsPackage

Allowance buckets for messages sent within the home country, including the base plan's SMS allowance and any add-on packages.

Show child attributes

subscriptionAddonIdstring

The subscription add-on that granted this allowance. Present only when the package comes from an add-on; absent for the base plan's included allowance.

namestringrequired

Human-readable name of the package, as shown to end users.

smsCountintegerint64required

Number of messages consumed from this allowance so far.

smsRemainingintegerint64required

Number of messages still available in this allowance.

smsTotalintegerint64required

The full message allowance of this package.

statusenum<string>required

The status of this package.

Whether a usage package is currently consumable.

ACTIVE: The package is in its validity window and usage draws from it
NOT_ACTIVE: The package exists but is not currently consumable, for example a purchased package whose validity window has not started yet
EXPIRED: The package's validity window has ended; any remaining allowance is no longer usable

values

ACTIVE
NOT_ACTIVE
EXPIRED

validFromstringdate-time

Start of the period this allowance applies to.

validTostringdate-time

End of the period this allowance applies to. For base plan allowances this is the end of the current billing period (when the allowance resets); for time-limited add-on packages it is when the package itself expires.

metadataobject with string keys

A set of key-value pairs that can be attached to an object for storing additional information in a semi-structured format. Provided by API clients and returned as-is; the platform does not interpret the values.

Show child attributes

roamingarray of UsageSmsPackage

Allowance buckets for messages sent while roaming abroad.

Show child attributes

subscriptionAddonIdstring

The subscription add-on that granted this allowance. Present only when the package comes from an add-on; absent for the base plan's included allowance.

namestringrequired

Human-readable name of the package, as shown to end users.

smsCountintegerint64required

Number of messages consumed from this allowance so far.

smsRemainingintegerint64required

Number of messages still available in this allowance.

smsTotalintegerint64required

The full message allowance of this package.

statusenum<string>required

The status of this package.

Whether a usage package is currently consumable.

ACTIVE: The package is in its validity window and usage draws from it
NOT_ACTIVE: The package exists but is not currently consumable, for example a purchased package whose validity window has not started yet
EXPIRED: The package's validity window has ended; any remaining allowance is no longer usable

values

ACTIVE
NOT_ACTIVE
EXPIRED

validFromstringdate-time

Start of the period this allowance applies to.

validTostringdate-time

End of the period this allowance applies to. For base plan allowances this is the end of the current billing period (when the allowance resets); for time-limited add-on packages it is when the package itself expires.

metadataobject with string keys

A set of key-value pairs that can be attached to an object for storing additional information in a semi-structured format. Provided by API clients and returned as-is; the platform does not interpret the values.

Show child attributes

ildarray of UsageSmsPackage

Allowance buckets for messages sent from the home country to foreign numbers (international long distance).

Show child attributes

subscriptionAddonIdstring

The subscription add-on that granted this allowance. Present only when the package comes from an add-on; absent for the base plan's included allowance.

namestringrequired

Human-readable name of the package, as shown to end users.

smsCountintegerint64required

Number of messages consumed from this allowance so far.

smsRemainingintegerint64required

Number of messages still available in this allowance.

smsTotalintegerint64required

The full message allowance of this package.

statusenum<string>required

The status of this package.

Whether a usage package is currently consumable.

ACTIVE: The package is in its validity window and usage draws from it
NOT_ACTIVE: The package exists but is not currently consumable, for example a purchased package whose validity window has not started yet
EXPIRED: The package's validity window has ended; any remaining allowance is no longer usable

values

ACTIVE
NOT_ACTIVE
EXPIRED

validFromstringdate-time

Start of the period this allowance applies to.

validTostringdate-time

End of the period this allowance applies to. For base plan allowances this is the end of the current billing period (when the allowance resets); for time-limited add-on packages it is when the package itself expires.

metadataobject with string keys

A set of key-value pairs that can be attached to an object for storing additional information in a semi-structured format. Provided by API clients and returned as-is; the platform does not interpret the values.

Show child attributes

mmsobject

MMS usage across all scopes and packages.

MMS (multimedia message) usage for a subscription, split by where and to whom messages are sent: national (domestic messages), roaming (messages sent while abroad), and ILD (international long distance — messages sent from the home country to foreign numbers).

Show child attributes

nationalarray of UsageMmsPackage

Allowance buckets for multimedia messages sent within the home country, including the base plan's MMS allowance and any add-on packages.

Show child attributes

subscriptionAddonIdstring

The subscription add-on that granted this allowance. Present only when the package comes from an add-on; absent for the base plan's included allowance.

namestringrequired

Human-readable name of the package, as shown to end users.

mmsCountintegerint64required

Number of multimedia messages consumed from this allowance so far.

mmsRemainingintegerint64required

Number of multimedia messages still available in this allowance.

mmsTotalintegerint64required

The full multimedia message allowance of this package.

validFromstringdate-time

Start of the period this allowance applies to.

validTostringdate-time

End of the period this allowance applies to. For base plan allowances this is the end of the current billing period (when the allowance resets); for time-limited add-on packages it is when the package itself expires.

metadataobject with string keys

A set of key-value pairs that can be attached to an object for storing additional information in a semi-structured format. Provided by API clients and returned as-is; the platform does not interpret the values.

Show child attributes

roamingarray of UsageMmsPackage

Allowance buckets for multimedia messages sent while roaming abroad.

Show child attributes

subscriptionAddonIdstring

The subscription add-on that granted this allowance. Present only when the package comes from an add-on; absent for the base plan's included allowance.

namestringrequired

Human-readable name of the package, as shown to end users.

mmsCountintegerint64required

Number of multimedia messages consumed from this allowance so far.

mmsRemainingintegerint64required

Number of multimedia messages still available in this allowance.

mmsTotalintegerint64required

The full multimedia message allowance of this package.

validFromstringdate-time

Start of the period this allowance applies to.

validTostringdate-time

End of the period this allowance applies to. For base plan allowances this is the end of the current billing period (when the allowance resets); for time-limited add-on packages it is when the package itself expires.

metadataobject with string keys

A set of key-value pairs that can be attached to an object for storing additional information in a semi-structured format. Provided by API clients and returned as-is; the platform does not interpret the values.

Show child attributes

ildarray of UsageMmsPackage

Allowance buckets for multimedia messages sent from the home country to foreign numbers (international long distance).

Show child attributes

subscriptionAddonIdstring

The subscription add-on that granted this allowance. Present only when the package comes from an add-on; absent for the base plan's included allowance.

namestringrequired

Human-readable name of the package, as shown to end users.

mmsCountintegerint64required

Number of multimedia messages consumed from this allowance so far.

mmsRemainingintegerint64required

Number of multimedia messages still available in this allowance.

mmsTotalintegerint64required

The full multimedia message allowance of this package.

validFromstringdate-time

Start of the period this allowance applies to.

validTostringdate-time

End of the period this allowance applies to. For base plan allowances this is the end of the current billing period (when the allowance resets); for time-limited add-on packages it is when the package itself expires.

metadataobject with string keys

A set of key-value pairs that can be attached to an object for storing additional information in a semi-structured format. Provided by API clients and returned as-is; the platform does not interpret the values.

Show child attributes

dataobject

Data usage across all scopes and packages.

Mobile data usage for a subscription, split by where the data is consumed: national (used in the home country) and roaming (used while abroad).

Show child attributes

nationalarray of UsageDataNationalPackage

Allowance buckets for data used in the home country, including the base plan's data allowance and any add-on packages.

Show child attributes

subscriptionAddonIdstring

The subscription add-on that granted this allowance. Present only when the package comes from an add-on; absent for the base plan's included allowance.

namestringrequired

Human-readable name of the package, as shown to end users.

dataBytesUsedintegerint64required

Data consumed from this allowance so far, in bytes.

dataBytesRemainingintegerint64required

Data still available in this allowance, in bytes.

dataBytesTotalintegerint64required

The full data allowance of this package, in bytes.

rlahBytesUsedintegerint64

Data consumed while roaming under RLAH (Roam Like At Home) rules, in bytes. Present only when the package includes an RLAH allowance.

rlahBytesRemainingintegerint64

RLAH data still available, in bytes. Once exhausted, roaming usage may incur additional charges even though national data remains.

rlahBytesTotalintegerint64

The portion of this package usable while roaming under RLAH rules, in bytes. Often lower than the full national allowance.

statusenum<string>required

The status of this package.

Whether a usage package is currently consumable.

ACTIVE: The package is in its validity window and usage draws from it
NOT_ACTIVE: The package exists but is not currently consumable, for example a purchased package whose validity window has not started yet
EXPIRED: The package's validity window has ended; any remaining allowance is no longer usable

values

ACTIVE
NOT_ACTIVE
EXPIRED

validFromstringdate-time

Start of the period this allowance applies to.

validTostringdate-time

End of the period this allowance applies to. For base plan allowances this is the end of the current billing period (when the allowance resets); for time-limited add-on packages it is when the package itself expires.

metadataobject with string keys

A set of key-value pairs that can be attached to an object for storing additional information in a semi-structured format. Provided by API clients and returned as-is; the platform does not interpret the values.

Show child attributes

roamingarray of UsageDataRoamingPackage

Allowance buckets for data used while roaming abroad, from the base plan's roaming allowance or dedicated roaming add-on packages.

Show child attributes

subscriptionAddonIdstring

The subscription add-on that granted this allowance. Present only when the package comes from an add-on; absent for the base plan's included roaming allowance.

namestringrequired

Human-readable name of the package, as shown to end users.

dataBytesUsedintegerint64required

Data consumed from this allowance so far, in bytes.

dataBytesRemainingintegerint64required

Data still available in this allowance, in bytes.

dataBytesTotalintegerint64required

The full data allowance of this package, in bytes.

statusenum<string>required

The status of this package.

Whether a usage package is currently consumable.

ACTIVE: The package is in its validity window and usage draws from it
NOT_ACTIVE: The package exists but is not currently consumable, for example a purchased package whose validity window has not started yet
EXPIRED: The package's validity window has ended; any remaining allowance is no longer usable

values

ACTIVE
NOT_ACTIVE
EXPIRED

validFromstringdate-time

Start of the period this allowance applies to.

validTostringdate-time

End of the period this allowance applies to. For base plan allowances this is the end of the current billing period (when the allowance resets); for time-limited add-on packages it is when the package itself expires.

metadataobject with string keys

A set of key-value pairs that can be attached to an object for storing additional information in a semi-structured format. Provided by API clients and returned as-is; the platform does not interpret the values.

Show child attributes

updatedAtstringdate-timerequired

When the usage information was last refreshed from the network. Usage counters are not real-time; recent activity may not be reflected yet.

400

The request was malformed or invalid.

application/json

The request was malformed or invalid.

objectError

The error body returned by every endpoint when a request fails. Use internalCode for programmatic handling, show message to a human, and check details for field-level problems when the request was invalid.

messagestringrequired

A human-readable message providing more details about the error.

codestringdeprecatedrequired

Deprecated. Use internalCode.

This field mixes three unrelated codes and does not say which one you have: a code that we publish, an operator's own code when the failure came from an operator, or the request status when there is neither. Do not branch on it.

internalCodestring

Names the condition that failed, from our own registry. It is independent of which system reported the failure and of the HTTP status, and it is stable across releases. Branch on this field. An unexpected failure on our side can carry no code. Then use the HTTP status.

detailsarray of object

Additional details about the error, typically one entry per invalid field on validation failures.

Show child attributes

messagestringrequired

A human-readable message providing more details about the error.

codestringrequired

A machine-readable code for the specific detail.

propertystring

The property or field related to the error. May be nested using dot notation (e.g., "billing.email").

suggestionone of

A suggested value for the particular property.

For example, this may be set when validating an address with an alias, suggesting the expected value by the operator.

A string, number, boolean, object, or array value. The concrete type depends on the field the value is returned for.

Show child attributes

hintstring

A hint to help resolve the error.

traceIdstring

Identifies the trace this request produced. Quote it when reporting a failure — it is what lets us find the request among everything else the platform served.

spanIdstring

The span within the trace that failed.

401

Authentication is required to access this resource.

application/json

Authentication is required to access this resource.

objectError

The error body returned by every endpoint when a request fails. Use internalCode for programmatic handling, show message to a human, and check details for field-level problems when the request was invalid.

messagestringrequired

A human-readable message providing more details about the error.

codestringdeprecatedrequired

Deprecated. Use internalCode.

This field mixes three unrelated codes and does not say which one you have: a code that we publish, an operator's own code when the failure came from an operator, or the request status when there is neither. Do not branch on it.

internalCodestring

Names the condition that failed, from our own registry. It is independent of which system reported the failure and of the HTTP status, and it is stable across releases. Branch on this field. An unexpected failure on our side can carry no code. Then use the HTTP status.

detailsarray of object

Additional details about the error, typically one entry per invalid field on validation failures.

Show child attributes

messagestringrequired

A human-readable message providing more details about the error.

codestringrequired

A machine-readable code for the specific detail.

propertystring

The property or field related to the error. May be nested using dot notation (e.g., "billing.email").

suggestionone of

A suggested value for the particular property.

For example, this may be set when validating an address with an alias, suggesting the expected value by the operator.

A string, number, boolean, object, or array value. The concrete type depends on the field the value is returned for.

Show child attributes

hintstring

A hint to help resolve the error.

traceIdstring

Identifies the trace this request produced. Quote it when reporting a failure — it is what lets us find the request among everything else the platform served.

spanIdstring

The span within the trace that failed.

403

Access to this resource is forbidden.

application/json

Access to this resource is forbidden.

objectError

The error body returned by every endpoint when a request fails. Use internalCode for programmatic handling, show message to a human, and check details for field-level problems when the request was invalid.

messagestringrequired

A human-readable message providing more details about the error.

codestringdeprecatedrequired

Deprecated. Use internalCode.

This field mixes three unrelated codes and does not say which one you have: a code that we publish, an operator's own code when the failure came from an operator, or the request status when there is neither. Do not branch on it.

internalCodestring

Names the condition that failed, from our own registry. It is independent of which system reported the failure and of the HTTP status, and it is stable across releases. Branch on this field. An unexpected failure on our side can carry no code. Then use the HTTP status.

detailsarray of object

Additional details about the error, typically one entry per invalid field on validation failures.

Show child attributes

messagestringrequired

A human-readable message providing more details about the error.

codestringrequired

A machine-readable code for the specific detail.

propertystring

The property or field related to the error. May be nested using dot notation (e.g., "billing.email").

suggestionone of

A suggested value for the particular property.

For example, this may be set when validating an address with an alias, suggesting the expected value by the operator.

A string, number, boolean, object, or array value. The concrete type depends on the field the value is returned for.

Show child attributes

hintstring

A hint to help resolve the error.

traceIdstring

Identifies the trace this request produced. Quote it when reporting a failure — it is what lets us find the request among everything else the platform served.

spanIdstring

The span within the trace that failed.

404

The requested resource was not found.

application/json

The requested resource was not found.

objectError

The error body returned by every endpoint when a request fails. Use internalCode for programmatic handling, show message to a human, and check details for field-level problems when the request was invalid.

messagestringrequired

A human-readable message providing more details about the error.

codestringdeprecatedrequired

Deprecated. Use internalCode.

This field mixes three unrelated codes and does not say which one you have: a code that we publish, an operator's own code when the failure came from an operator, or the request status when there is neither. Do not branch on it.

internalCodestring

Names the condition that failed, from our own registry. It is independent of which system reported the failure and of the HTTP status, and it is stable across releases. Branch on this field. An unexpected failure on our side can carry no code. Then use the HTTP status.

detailsarray of object

Additional details about the error, typically one entry per invalid field on validation failures.

Show child attributes

messagestringrequired

A human-readable message providing more details about the error.

codestringrequired

A machine-readable code for the specific detail.

propertystring

The property or field related to the error. May be nested using dot notation (e.g., "billing.email").

suggestionone of

A suggested value for the particular property.

For example, this may be set when validating an address with an alias, suggesting the expected value by the operator.

A string, number, boolean, object, or array value. The concrete type depends on the field the value is returned for.

Show child attributes

hintstring

A hint to help resolve the error.

traceIdstring

Identifies the trace this request produced. Quote it when reporting a failure — it is what lets us find the request among everything else the platform served.

spanIdstring

The span within the trace that failed.

500

An unexpected error occurred on the server.

application/json

An unexpected error occurred on the server.

objectError

The error body returned by every endpoint when a request fails. Use internalCode for programmatic handling, show message to a human, and check details for field-level problems when the request was invalid.

messagestringrequired

A human-readable message providing more details about the error.

codestringdeprecatedrequired

Deprecated. Use internalCode.

This field mixes three unrelated codes and does not say which one you have: a code that we publish, an operator's own code when the failure came from an operator, or the request status when there is neither. Do not branch on it.

internalCodestring

Names the condition that failed, from our own registry. It is independent of which system reported the failure and of the HTTP status, and it is stable across releases. Branch on this field. An unexpected failure on our side can carry no code. Then use the HTTP status.

detailsarray of object

Additional details about the error, typically one entry per invalid field on validation failures.

Show child attributes

messagestringrequired

A human-readable message providing more details about the error.

codestringrequired

A machine-readable code for the specific detail.

propertystring

The property or field related to the error. May be nested using dot notation (e.g., "billing.email").

suggestionone of

A suggested value for the particular property.

For example, this may be set when validating an address with an alias, suggesting the expected value by the operator.

A string, number, boolean, object, or array value. The concrete type depends on the field the value is returned for.

Show child attributes

hintstring

A hint to help resolve the error.

traceIdstring

Identifies the trace this request produced. Quote it when reporting a failure — it is what lets us find the request among everything else the platform served.

spanIdstring

The span within the trace that failed.

Auth required

Send one of

X-Api-Key
Bearer JWT + X-Api-Key

The API key is always required; the bearer token is optional.

GET /subscriptions/{subscriptionId}/usage

curl https://apiv2.example.com/api/v2/subscriptions/SUBSCRIPTION_ID/usage \
  --header 'Authorization: Bearer YOUR_ACCESS_TOKEN' \
  --header 'X-Api-Key: YOUR_API_KEY'

fetch('https://apiv2.example.com/api/v2/subscriptions/SUBSCRIPTION_ID/usage', {
  headers: {
    Authorization: 'Bearer YOUR_ACCESS_TOKEN',
    'X-Api-Key': 'YOUR_API_KEY'
  }
})

requests.get(
    "https://apiv2.example.com/api/v2/subscriptions/SUBSCRIPTION_ID/usage",
    headers={
      "Authorization": "Bearer YOUR_ACCESS_TOKEN",
      "X-Api-Key": "YOUR_API_KEY"
    }
)

package main

import (
	"fmt"
	"io"
	"net/http"
)

func main() {
	requestUrl := "https://apiv2.example.com/api/v2/subscriptions/SUBSCRIPTION_ID/usage"

	req, _ := http.NewRequest("GET", requestUrl, nil)

	req.Header.Add("Authorization", "Bearer YOUR_ACCESS_TOKEN")
	req.Header.Add("X-Api-Key", "YOUR_API_KEY")

	res, _ := http.DefaultClient.Do(req)

	defer res.Body.Close()
	body, _ := io.ReadAll(res.Body)

	fmt.Println(res)
	fmt.Println(string(body))

}

{
  "voice": {
    "national": [
      {
        "name": "Unlimited National",
        "callSeconds": 3600,
        "callCount": 15,
        "callRemainingSeconds": 32400,
        "callTotalSeconds": 36000,
        "status": "ACTIVE",
        "validFrom": "2025-01-01T00:00:00Z",
        "validTo": "2025-02-01T00:00:00Z"
      }
    ],
    "ild": [
      {
        "name": "ILD Top-up",
        "balanceMinor": 1550,
        "currency": "USD",
        "expiryDate": "2025-12-31"
      }
    ]
  },
  "sms": {
    "national": [
      {
        "name": "500 SMS National",
        "smsCount": 25,
        "smsRemaining": 475,
        "smsTotal": 500,
        "status": "ACTIVE",
        "validFrom": "2025-01-01T00:00:00Z",
        "validTo": "2025-02-01T00:00:00Z"
      }
    ]
  },
  "data": {
    "national": [
      {
        "name": "10GB National",
        "dataBytesUsed": 3221225472,
        "dataBytesRemaining": 7516192768,
        "dataBytesTotal": 10737418240,
        "status": "ACTIVE",
        "validFrom": "2025-01-01T00:00:00Z",
        "validTo": "2025-02-01T00:00:00Z"
      }
    ],
    "roaming": [
      {
        "name": "Asia 5GB Roaming",
        "subscriptionAddonId": "a47ac10b-58cc-4372-a567-0e02b2c3d479",
        "dataBytesUsed": 1073741824,
        "dataBytesRemaining": 4294967296,
        "dataBytesTotal": 5368709120,
        "status": "ACTIVE",
        "validFrom": "2025-01-01T00:00:00Z",
        "validTo": "2025-02-01T00:00:00Z"
      }
    ]
  },
  "updatedAt": "2025-01-15T10:30:00Z"
}

{
  "message": "The request body is invalid.",
  "code": "bad_request",
  "details": [
    {
      "message": "Email format is invalid.",
      "code": "invalid_email",
      "property": "contact.email"
    }
  ],
  "hint": "Check the request payload and correct the highlighted fields."
}

{
  "message": "Authentication is required to access this resource.",
  "code": "unauthorized",
  "hint": "Provide a valid API key in the X-Api-Key header."
}

{
  "message": "You do not have permission to perform this action.",
  "code": "forbidden",
  "hint": "Ensure your API key or user has the required permissions."
}

{
  "message": "The requested customer could not be found.",
  "code": "not_found",
  "hint": "Verify the customerId and try again."
}

{
  "message": "An unexpected error occurred on the server.",
  "code": "internal_server_error",
  "hint": "Retry the request later. If the problem persists, contact support."
}

Get usage for multiple subscriptions

GET/subscriptions/usage

Retrieve current usage statistics for multiple subscriptions by providing their IDs.

Query parameters

subscriptionIdsarray of stringmin items 1max items 100required

List of subscription IDs to retrieve usage for.

Responses

200

Usage statistics for the requested subscriptions.

application/json

Usage statistics for the requested subscriptions.

object

itemsarray of objectrequired

Usage information for each requested subscription.

Show child attributes

subscriptionIdstringrequired

The unique identifier for the subscription.

usageobjectrequired

Current usage statistics for a subscription, organized by service type (voice, SMS, MMS, data). Within each service type, usage is broken down into per-package allowance buckets: the base plan's included allowance plus any add-on packages, each reporting used, remaining, and total amounts. A service type is omitted entirely when the subscription has no allowances of that type.

Show child attributes

voiceobject

Voice call usage across all scopes and packages.

Voice call usage for a subscription, split by where and to whom calls are made: national (domestic calls), roaming (calls made while abroad), and ILD (international long distance — calls placed from the home country to foreign numbers).

Show child attributes

smsobject

SMS usage across all scopes and packages.

SMS usage for a subscription, split by where and to whom messages are sent: national (domestic messages), roaming (messages sent while abroad), and ILD (international long distance — messages sent from the home country to foreign numbers).

Show child attributes

mmsobject

MMS usage across all scopes and packages.

MMS (multimedia message) usage for a subscription, split by where and to whom messages are sent: national (domestic messages), roaming (messages sent while abroad), and ILD (international long distance — messages sent from the home country to foreign numbers).

Show child attributes

dataobject

Data usage across all scopes and packages.

Mobile data usage for a subscription, split by where the data is consumed: national (used in the home country) and roaming (used while abroad).

Show child attributes

updatedAtstringdate-timerequired

When the usage information was last refreshed from the network. Usage counters are not real-time; recent activity may not be reflected yet.

400

The request was malformed or invalid.

application/json

The request was malformed or invalid.

objectError

The error body returned by every endpoint when a request fails. Use internalCode for programmatic handling, show message to a human, and check details for field-level problems when the request was invalid.

messagestringrequired

A human-readable message providing more details about the error.

codestringdeprecatedrequired

Deprecated. Use internalCode.

This field mixes three unrelated codes and does not say which one you have: a code that we publish, an operator's own code when the failure came from an operator, or the request status when there is neither. Do not branch on it.

internalCodestring

Names the condition that failed, from our own registry. It is independent of which system reported the failure and of the HTTP status, and it is stable across releases. Branch on this field. An unexpected failure on our side can carry no code. Then use the HTTP status.

detailsarray of object

Additional details about the error, typically one entry per invalid field on validation failures.

Show child attributes

messagestringrequired

A human-readable message providing more details about the error.

codestringrequired

A machine-readable code for the specific detail.

propertystring

The property or field related to the error. May be nested using dot notation (e.g., "billing.email").

suggestionone of

A suggested value for the particular property.

For example, this may be set when validating an address with an alias, suggesting the expected value by the operator.

A string, number, boolean, object, or array value. The concrete type depends on the field the value is returned for.

Show child attributes

hintstring

A hint to help resolve the error.

traceIdstring

Identifies the trace this request produced. Quote it when reporting a failure — it is what lets us find the request among everything else the platform served.

spanIdstring

The span within the trace that failed.

401

Authentication is required to access this resource.

application/json

Authentication is required to access this resource.

objectError

The error body returned by every endpoint when a request fails. Use internalCode for programmatic handling, show message to a human, and check details for field-level problems when the request was invalid.

messagestringrequired

A human-readable message providing more details about the error.

codestringdeprecatedrequired

Deprecated. Use internalCode.

This field mixes three unrelated codes and does not say which one you have: a code that we publish, an operator's own code when the failure came from an operator, or the request status when there is neither. Do not branch on it.

internalCodestring

Names the condition that failed, from our own registry. It is independent of which system reported the failure and of the HTTP status, and it is stable across releases. Branch on this field. An unexpected failure on our side can carry no code. Then use the HTTP status.

detailsarray of object

Additional details about the error, typically one entry per invalid field on validation failures.

Show child attributes

messagestringrequired

A human-readable message providing more details about the error.

codestringrequired

A machine-readable code for the specific detail.

propertystring

The property or field related to the error. May be nested using dot notation (e.g., "billing.email").

suggestionone of

A suggested value for the particular property.

For example, this may be set when validating an address with an alias, suggesting the expected value by the operator.

A string, number, boolean, object, or array value. The concrete type depends on the field the value is returned for.

Show child attributes

hintstring

A hint to help resolve the error.

traceIdstring

Identifies the trace this request produced. Quote it when reporting a failure — it is what lets us find the request among everything else the platform served.

spanIdstring

The span within the trace that failed.

403

Access to this resource is forbidden.

application/json

Access to this resource is forbidden.

objectError

The error body returned by every endpoint when a request fails. Use internalCode for programmatic handling, show message to a human, and check details for field-level problems when the request was invalid.

messagestringrequired

A human-readable message providing more details about the error.

codestringdeprecatedrequired

Deprecated. Use internalCode.

This field mixes three unrelated codes and does not say which one you have: a code that we publish, an operator's own code when the failure came from an operator, or the request status when there is neither. Do not branch on it.

internalCodestring

Names the condition that failed, from our own registry. It is independent of which system reported the failure and of the HTTP status, and it is stable across releases. Branch on this field. An unexpected failure on our side can carry no code. Then use the HTTP status.

detailsarray of object

Additional details about the error, typically one entry per invalid field on validation failures.

Show child attributes

messagestringrequired

A human-readable message providing more details about the error.

codestringrequired

A machine-readable code for the specific detail.

propertystring

The property or field related to the error. May be nested using dot notation (e.g., "billing.email").

suggestionone of

A suggested value for the particular property.

For example, this may be set when validating an address with an alias, suggesting the expected value by the operator.

A string, number, boolean, object, or array value. The concrete type depends on the field the value is returned for.

Show child attributes

hintstring

A hint to help resolve the error.

traceIdstring

Identifies the trace this request produced. Quote it when reporting a failure — it is what lets us find the request among everything else the platform served.

spanIdstring

The span within the trace that failed.

404

The requested resource was not found.

application/json

The requested resource was not found.

objectError

The error body returned by every endpoint when a request fails. Use internalCode for programmatic handling, show message to a human, and check details for field-level problems when the request was invalid.

messagestringrequired

A human-readable message providing more details about the error.

codestringdeprecatedrequired

Deprecated. Use internalCode.

This field mixes three unrelated codes and does not say which one you have: a code that we publish, an operator's own code when the failure came from an operator, or the request status when there is neither. Do not branch on it.

internalCodestring

Names the condition that failed, from our own registry. It is independent of which system reported the failure and of the HTTP status, and it is stable across releases. Branch on this field. An unexpected failure on our side can carry no code. Then use the HTTP status.

detailsarray of object

Additional details about the error, typically one entry per invalid field on validation failures.

Show child attributes

messagestringrequired

A human-readable message providing more details about the error.

codestringrequired

A machine-readable code for the specific detail.

propertystring

The property or field related to the error. May be nested using dot notation (e.g., "billing.email").

suggestionone of

A suggested value for the particular property.

For example, this may be set when validating an address with an alias, suggesting the expected value by the operator.

A string, number, boolean, object, or array value. The concrete type depends on the field the value is returned for.

Show child attributes

hintstring

A hint to help resolve the error.

traceIdstring

Identifies the trace this request produced. Quote it when reporting a failure — it is what lets us find the request among everything else the platform served.

spanIdstring

The span within the trace that failed.

500

An unexpected error occurred on the server.

application/json

An unexpected error occurred on the server.

objectError

The error body returned by every endpoint when a request fails. Use internalCode for programmatic handling, show message to a human, and check details for field-level problems when the request was invalid.

messagestringrequired

A human-readable message providing more details about the error.

codestringdeprecatedrequired

Deprecated. Use internalCode.

This field mixes three unrelated codes and does not say which one you have: a code that we publish, an operator's own code when the failure came from an operator, or the request status when there is neither. Do not branch on it.

internalCodestring

Names the condition that failed, from our own registry. It is independent of which system reported the failure and of the HTTP status, and it is stable across releases. Branch on this field. An unexpected failure on our side can carry no code. Then use the HTTP status.

detailsarray of object

Additional details about the error, typically one entry per invalid field on validation failures.

Show child attributes

messagestringrequired

A human-readable message providing more details about the error.

codestringrequired

A machine-readable code for the specific detail.

propertystring

The property or field related to the error. May be nested using dot notation (e.g., "billing.email").

suggestionone of

A suggested value for the particular property.

For example, this may be set when validating an address with an alias, suggesting the expected value by the operator.

A string, number, boolean, object, or array value. The concrete type depends on the field the value is returned for.

Show child attributes

hintstring

A hint to help resolve the error.

traceIdstring

Identifies the trace this request produced. Quote it when reporting a failure — it is what lets us find the request among everything else the platform served.

spanIdstring

The span within the trace that failed.

Auth required

Send one of

X-Api-Key
Bearer JWT + X-Api-Key

The API key is always required; the bearer token is optional.

GET /subscriptions/usage

curl 'https://apiv2.example.com/api/v2/subscriptions/usage?subscriptionIds=SUBSCRIPTION_IDS' \
  --header 'Authorization: Bearer YOUR_ACCESS_TOKEN' \
  --header 'X-Api-Key: YOUR_API_KEY'

fetch('https://apiv2.example.com/api/v2/subscriptions/usage?subscriptionIds=SUBSCRIPTION_IDS', {
  headers: {
    Authorization: 'Bearer YOUR_ACCESS_TOKEN',
    'X-Api-Key': 'YOUR_API_KEY'
  }
})

requests.get(
    "https://apiv2.example.com/api/v2/subscriptions/usage",
    headers={
      "Authorization": "Bearer YOUR_ACCESS_TOKEN",
      "X-Api-Key": "YOUR_API_KEY"
    },
    params={
      "subscriptionIds": "SUBSCRIPTION_IDS"
    }
)

package main

import (
	"fmt"
	"io"
	"net/http"
)

func main() {
	requestUrl := "https://apiv2.example.com/api/v2/subscriptions/usage?subscriptionIds=SUBSCRIPTION_IDS"

	req, _ := http.NewRequest("GET", requestUrl, nil)

	req.Header.Add("Authorization", "Bearer YOUR_ACCESS_TOKEN")
	req.Header.Add("X-Api-Key", "YOUR_API_KEY")

	res, _ := http.DefaultClient.Do(req)

	defer res.Body.Close()
	body, _ := io.ReadAll(res.Body)

	fmt.Println(res)
	fmt.Println(string(body))

}

{
  "items": [
    {
      "subscriptionId": "123e4567-e89b-12d3-a456-426614174000",
      "usage": {
        "voice": {
          "national": [
            {
              "subscriptionAddonId": "f47ac10b-58cc-4372-a567-0e02b2c3d479",
              "name": "Unlimited National",
              "callSeconds": 3600,
              "callCount": 15,
              "callRemainingSeconds": 32400,
              "callTotalSeconds": 36000,
              "status": "ACTIVE",
              "validFrom": "2025-01-01T00:00:00Z",
              "validTo": "2025-02-01T00:00:00Z",
              "metadata": {
                "propertyName": "string"
              }
            }
          ],
          "roaming": [
            {
              "subscriptionAddonId": "f47ac10b-58cc-4372-a567-0e02b2c3d479",
              "name": "Unlimited National",
              "callSeconds": 3600,
              "callCount": 15,
              "callRemainingSeconds": 32400,
              "callTotalSeconds": 36000,
              "status": "ACTIVE",
              "validFrom": "2025-01-01T00:00:00Z",
              "validTo": "2025-02-01T00:00:00Z",
              "metadata": {
                "propertyName": "string"
              }
            }
          ],
          "ild": [
            {
              "subscriptionAddonId": "f47ac10b-58cc-4372-a567-0e02b2c3d479",
              "name": "ILD Top-up",
              "balanceMinor": 1550,
              "currency": "USD",
              "expiryDate": "2025-12-31",
              "metadata": {
                "propertyName": "string"
              }
            }
          ]
        },
        "sms": {
          "national": [
            {
              "subscriptionAddonId": "f47ac10b-58cc-4372-a567-0e02b2c3d479",
              "name": "500 SMS National",
              "smsCount": 25,
              "smsRemaining": 475,
              "smsTotal": 500,
              "status": "ACTIVE",
              "validFrom": "2025-01-01T00:00:00Z",
              "validTo": "2025-02-01T00:00:00Z",
              "metadata": {
                "propertyName": "string"
              }
            }
          ],
          "roaming": [
            {
              "subscriptionAddonId": "f47ac10b-58cc-4372-a567-0e02b2c3d479",
              "name": "500 SMS National",
              "smsCount": 25,
              "smsRemaining": 475,
              "smsTotal": 500,
              "status": "ACTIVE",
              "validFrom": "2025-01-01T00:00:00Z",
              "validTo": "2025-02-01T00:00:00Z",
              "metadata": {
                "propertyName": "string"
              }
            }
          ],
          "ild": [
            {
              "subscriptionAddonId": "f47ac10b-58cc-4372-a567-0e02b2c3d479",
              "name": "500 SMS National",
              "smsCount": 25,
              "smsRemaining": 475,
              "smsTotal": 500,
              "status": "ACTIVE",
              "validFrom": "2025-01-01T00:00:00Z",
              "validTo": "2025-02-01T00:00:00Z",
              "metadata": {
                "propertyName": "string"
              }
            }
          ]
        },
        "mms": {
          "national": [
            {
              "subscriptionAddonId": "f47ac10b-58cc-4372-a567-0e02b2c3d479",
              "name": "100 MMS National",
              "mmsCount": 10,
              "mmsRemaining": 90,
              "mmsTotal": 100,
              "validFrom": "2025-01-01T00:00:00Z",
              "validTo": "2025-02-01T00:00:00Z",
              "metadata": {
                "propertyName": "string"
              }
            }
          ],
          "roaming": [
            {
              "subscriptionAddonId": "f47ac10b-58cc-4372-a567-0e02b2c3d479",
              "name": "100 MMS National",
              "mmsCount": 10,
              "mmsRemaining": 90,
              "mmsTotal": 100,
              "validFrom": "2025-01-01T00:00:00Z",
              "validTo": "2025-02-01T00:00:00Z",
              "metadata": {
                "propertyName": "string"
              }
            }
          ],
          "ild": [
            {
              "subscriptionAddonId": "f47ac10b-58cc-4372-a567-0e02b2c3d479",
              "name": "100 MMS National",
              "mmsCount": 10,
              "mmsRemaining": 90,
              "mmsTotal": 100,
              "validFrom": "2025-01-01T00:00:00Z",
              "validTo": "2025-02-01T00:00:00Z",
              "metadata": {
                "propertyName": "string"
              }
            }
          ]
        },
        "data": {
          "national": [
            {
              "subscriptionAddonId": "f47ac10b-58cc-4372-a567-0e02b2c3d479",
              "name": "10GB National",
              "dataBytesUsed": 3221225472,
              "dataBytesRemaining": 7516192768,
              "dataBytesTotal": 10737418240,
              "rlahBytesUsed": 1073741824,
              "rlahBytesRemaining": 4294967296,
              "rlahBytesTotal": 5368709120,
              "status": "ACTIVE",
              "validFrom": "2025-01-01T00:00:00Z",
              "validTo": "2025-02-01T00:00:00Z",
              "metadata": {
                "propertyName": "string"
              }
            }
          ],
          "roaming": [
            {
              "subscriptionAddonId": "f47ac10b-58cc-4372-a567-0e02b2c3d479",
              "name": "Asia 5GB Roaming",
              "dataBytesUsed": 1073741824,
              "dataBytesRemaining": 4294967296,
              "dataBytesTotal": 5368709120,
              "status": "ACTIVE",
              "validFrom": "2025-01-01T00:00:00Z",
              "validTo": "2025-02-01T00:00:00Z",
              "metadata": {
                "propertyName": "string"
              }
            }
          ]
        },
        "updatedAt": "2024-01-15T10:30:00Z"
      }
    }
  ]
}

{
  "message": "The request body is invalid.",
  "code": "bad_request",
  "details": [
    {
      "message": "Email format is invalid.",
      "code": "invalid_email",
      "property": "contact.email"
    }
  ],
  "hint": "Check the request payload and correct the highlighted fields."
}

{
  "message": "Authentication is required to access this resource.",
  "code": "unauthorized",
  "hint": "Provide a valid API key in the X-Api-Key header."
}

{
  "message": "You do not have permission to perform this action.",
  "code": "forbidden",
  "hint": "Ensure your API key or user has the required permissions."
}

{
  "message": "The requested customer could not be found.",
  "code": "not_found",
  "hint": "Verify the customerId and try again."
}

{
  "message": "An unexpected error occurred on the server.",
  "code": "internal_server_error",
  "hint": "Retry the request later. If the problem persists, contact support."
}