Valdyr
View as MarkdownOpen in ClaudeOpen in ChatGPT

Subscription Usage

The data, voice and SMS usage of a subscription.

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.

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
dataBytesRemainingintegerint64required

Data still available in this allowance, in bytes.

dataBytesTotalintegerint64required

The full data allowance of this package, in bytes.

dataBytesUsedintegerint64required

Data consumed from this allowance so far, in bytes.

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
namestringrequired

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

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.

rlahBytesUsedintegerint64

Data consumed while roaming under RLAH (Roam Like At Home) rules, in bytes. Present only when the package includes an RLAH 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
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.

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.

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
dataBytesRemainingintegerint64required

Data still available in this allowance, in bytes.

dataBytesTotalintegerint64required

The full data allowance of this package, in bytes.

dataBytesUsedintegerint64required

Data consumed from this allowance so far, in bytes.

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
namestringrequired

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

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

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.

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
ildarray of UsageMmsPackage

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

Show child attributes
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
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.

namestringrequired

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

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.

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.

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

namestringrequired

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

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.

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.

roamingarray of UsageMmsPackage

Allowance buckets for multimedia messages sent while roaming abroad.

Show child attributes
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
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.

namestringrequired

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

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.

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.

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
ildarray of UsageSmsPackage

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

Show child attributes
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
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
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.

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.

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

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.

roamingarray of UsageSmsPackage

Allowance buckets for messages sent while roaming abroad.

Show child attributes
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
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
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.

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.

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.

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
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
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
namestringrequired

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

subscriptionAddonIdstring

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

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
callCountintegerint64required

Number of calls placed against this allowance.

callRemainingSecondsintegerint64required

Call time still available in this allowance, in seconds.

callSecondsintegerint64required

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

callTotalSecondsintegerint64required

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

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
namestringrequired

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

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

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.

roamingarray of UsageVoicePackage

Allowance buckets for calls made while roaming abroad.

Show child attributes
callCountintegerint64required

Number of calls placed against this allowance.

callRemainingSecondsintegerint64required

Call time still available in this allowance, in seconds.

callSecondsintegerint64required

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

callTotalSecondsintegerint64required

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

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
namestringrequired

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

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

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.

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. Branch on reason, show message to a human, and check details for field-level problems when the request was invalid.

codestringdeprecatedrequired

Deprecated. Use reason.

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.

detailsarray of object

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

Show child attributes
codestringdeprecatedrequired

Deprecated. Use reason. It is the status of the whole error, the same for each item.

messagestringrequired

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

propertystring

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

reasonstring

Names the problem with the property. property_required is a missing value, property_invalid is a value with the wrong format, and property_conflict is two values that cannot occur together. Other reasons name a business condition. Your client must accept a reason that it does not know.

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
domainstring

The business area of the reason, for example customer or porting. It is for information only. Do not branch on it.

externalCodestring

The code that a third party, for example a network operator, sent for the failure. It is exactly as the third party sent it.

externalSourcestring

The third party that reported the failure.

hintstring

A hint to help resolve the error.

internalCodestring

The number of the condition that failed. It is stable across releases. A condition that we added after reason has no number, so branch on reason instead.

messagestringrequired

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

reasonstring

Names the condition that failed, in lower snake_case. It is independent of which system reported the failure, and it is stable across releases. Branch on this field. We add new reasons without notice, so your client must accept a reason that it does not know.

If the request has problems with different reasons, the reason is validation_failed. Then each item of details names its own problem.

retryableboolean

True when the same request can pass later with no change. A 429 and a 503 are always retryable.

spanIdstring

The span within the trace that failed.

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.

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. Branch on reason, show message to a human, and check details for field-level problems when the request was invalid.

codestringdeprecatedrequired

Deprecated. Use reason.

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.

detailsarray of object

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

Show child attributes
codestringdeprecatedrequired

Deprecated. Use reason. It is the status of the whole error, the same for each item.

messagestringrequired

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

propertystring

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

reasonstring

Names the problem with the property. property_required is a missing value, property_invalid is a value with the wrong format, and property_conflict is two values that cannot occur together. Other reasons name a business condition. Your client must accept a reason that it does not know.

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
domainstring

The business area of the reason, for example customer or porting. It is for information only. Do not branch on it.

externalCodestring

The code that a third party, for example a network operator, sent for the failure. It is exactly as the third party sent it.

externalSourcestring

The third party that reported the failure.

hintstring

A hint to help resolve the error.

internalCodestring

The number of the condition that failed. It is stable across releases. A condition that we added after reason has no number, so branch on reason instead.

messagestringrequired

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

reasonstring

Names the condition that failed, in lower snake_case. It is independent of which system reported the failure, and it is stable across releases. Branch on this field. We add new reasons without notice, so your client must accept a reason that it does not know.

If the request has problems with different reasons, the reason is validation_failed. Then each item of details names its own problem.

retryableboolean

True when the same request can pass later with no change. A 429 and a 503 are always retryable.

spanIdstring

The span within the trace that failed.

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.

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. Branch on reason, show message to a human, and check details for field-level problems when the request was invalid.

codestringdeprecatedrequired

Deprecated. Use reason.

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.

detailsarray of object

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

Show child attributes
codestringdeprecatedrequired

Deprecated. Use reason. It is the status of the whole error, the same for each item.

messagestringrequired

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

propertystring

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

reasonstring

Names the problem with the property. property_required is a missing value, property_invalid is a value with the wrong format, and property_conflict is two values that cannot occur together. Other reasons name a business condition. Your client must accept a reason that it does not know.

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
domainstring

The business area of the reason, for example customer or porting. It is for information only. Do not branch on it.

externalCodestring

The code that a third party, for example a network operator, sent for the failure. It is exactly as the third party sent it.

externalSourcestring

The third party that reported the failure.

hintstring

A hint to help resolve the error.

internalCodestring

The number of the condition that failed. It is stable across releases. A condition that we added after reason has no number, so branch on reason instead.

messagestringrequired

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

reasonstring

Names the condition that failed, in lower snake_case. It is independent of which system reported the failure, and it is stable across releases. Branch on this field. We add new reasons without notice, so your client must accept a reason that it does not know.

If the request has problems with different reasons, the reason is validation_failed. Then each item of details names its own problem.

retryableboolean

True when the same request can pass later with no change. A 429 and a 503 are always retryable.

spanIdstring

The span within the trace that failed.

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.

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. Branch on reason, show message to a human, and check details for field-level problems when the request was invalid.

codestringdeprecatedrequired

Deprecated. Use reason.

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.

detailsarray of object

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

Show child attributes
codestringdeprecatedrequired

Deprecated. Use reason. It is the status of the whole error, the same for each item.

messagestringrequired

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

propertystring

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

reasonstring

Names the problem with the property. property_required is a missing value, property_invalid is a value with the wrong format, and property_conflict is two values that cannot occur together. Other reasons name a business condition. Your client must accept a reason that it does not know.

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
domainstring

The business area of the reason, for example customer or porting. It is for information only. Do not branch on it.

externalCodestring

The code that a third party, for example a network operator, sent for the failure. It is exactly as the third party sent it.

externalSourcestring

The third party that reported the failure.

hintstring

A hint to help resolve the error.

internalCodestring

The number of the condition that failed. It is stable across releases. A condition that we added after reason has no number, so branch on reason instead.

messagestringrequired

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

reasonstring

Names the condition that failed, in lower snake_case. It is independent of which system reported the failure, and it is stable across releases. Branch on this field. We add new reasons without notice, so your client must accept a reason that it does not know.

If the request has problems with different reasons, the reason is validation_failed. Then each item of details names its own problem.

retryableboolean

True when the same request can pass later with no change. A 429 and a 503 are always retryable.

spanIdstring

The span within the trace that failed.

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.

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. Branch on reason, show message to a human, and check details for field-level problems when the request was invalid.

codestringdeprecatedrequired

Deprecated. Use reason.

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.

detailsarray of object

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

Show child attributes
codestringdeprecatedrequired

Deprecated. Use reason. It is the status of the whole error, the same for each item.

messagestringrequired

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

propertystring

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

reasonstring

Names the problem with the property. property_required is a missing value, property_invalid is a value with the wrong format, and property_conflict is two values that cannot occur together. Other reasons name a business condition. Your client must accept a reason that it does not know.

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
domainstring

The business area of the reason, for example customer or porting. It is for information only. Do not branch on it.

externalCodestring

The code that a third party, for example a network operator, sent for the failure. It is exactly as the third party sent it.

externalSourcestring

The third party that reported the failure.

hintstring

A hint to help resolve the error.

internalCodestring

The number of the condition that failed. It is stable across releases. A condition that we added after reason has no number, so branch on reason instead.

messagestringrequired

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

reasonstring

Names the condition that failed, in lower snake_case. It is independent of which system reported the failure, and it is stable across releases. Branch on this field. We add new reasons without notice, so your client must accept a reason that it does not know.

If the request has problems with different reasons, the reason is validation_failed. Then each item of details names its own problem.

retryableboolean

True when the same request can pass later with no change. A 429 and a 503 are always retryable.

spanIdstring

The span within the trace that failed.

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.

Auth required

Send

  • X-Api-Key + Bearer JWT
GET /subscriptions/{subscriptionId}/usage
curl https://apiv2.example.com/api/v2/end-user/subscriptions/SUBSCRIPTION_ID/usage \
  --header 'X-Api-Key: YOUR_API_KEY' \
  --header 'Authorization: Bearer YOUR_ACCESS_TOKEN'
fetch('https://apiv2.example.com/api/v2/end-user/subscriptions/SUBSCRIPTION_ID/usage', {
  headers: {
    'X-Api-Key': 'YOUR_API_KEY',
    Authorization: 'Bearer YOUR_ACCESS_TOKEN'
  }
})
requests.get(
    "https://apiv2.example.com/api/v2/end-user/subscriptions/SUBSCRIPTION_ID/usage",
    headers={
      "X-Api-Key": "YOUR_API_KEY",
      "Authorization": "Bearer YOUR_ACCESS_TOKEN"
    }
)
package main

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

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

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

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

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

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

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

}
{
  "data": {
    "national": [
      {
        "dataBytesRemaining": 7516192768,
        "dataBytesTotal": 10737418240,
        "dataBytesUsed": 3221225472,
        "name": "10GB National",
        "status": "ACTIVE",
        "validFrom": "2025-01-01T00:00:00Z",
        "validTo": "2025-02-01T00:00:00Z"
      }
    ],
    "roaming": [
      {
        "dataBytesRemaining": 4294967296,
        "dataBytesTotal": 5368709120,
        "dataBytesUsed": 1073741824,
        "name": "Asia 5GB Roaming",
        "status": "ACTIVE",
        "subscriptionAddonId": "a47ac10b-58cc-4372-a567-0e02b2c3d479",
        "validFrom": "2025-01-01T00:00:00Z",
        "validTo": "2025-02-01T00:00:00Z"
      }
    ]
  },
  "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"
      }
    ]
  },
  "updatedAt": "2025-01-15T10:30:00Z",
  "voice": {
    "ild": [
      {
        "balanceMinor": 1550,
        "currency": "USD",
        "expiryDate": "2025-12-31",
        "name": "ILD Top-up"
      }
    ],
    "national": [
      {
        "callCount": 15,
        "callRemainingSeconds": 32400,
        "callSeconds": 3600,
        "callTotalSeconds": 36000,
        "name": "Unlimited National",
        "status": "ACTIVE",
        "validFrom": "2025-01-01T00:00:00Z",
        "validTo": "2025-02-01T00:00:00Z"
      }
    ]
  }
}
{
  "code": "bad_request",
  "details": [
    {
      "code": "invalid_email",
      "message": "Email format is invalid.",
      "property": "contact.email"
    }
  ],
  "hint": "Check the request payload and correct the highlighted fields.",
  "message": "The request body is invalid."
}
{
  "code": "unauthorized",
  "hint": "Provide a valid API key in the X-Api-Key header.",
  "message": "Authentication is required to access this resource."
}
{
  "code": "forbidden",
  "hint": "Ensure your API key or user has the required permissions.",
  "message": "You do not have permission to perform this action."
}
{
  "code": "not_found",
  "hint": "Verify the customerId and try again.",
  "message": "The requested customer could not be found."
}
{
  "code": "internal_server_error",
  "hint": "Retry the request later. If the problem persists, contact support.",
  "message": "An unexpected error occurred on the server."
}