--- title: Subscription Usage description: Get subscription usage. --- # Subscription Usage Get subscription usage. ## [GET /subscriptions/{subscriptionId}/usage](/api-reference/subscription-usage#tag/subscription-usage/GET/subscriptions/{subscriptionId}/usage) Get subscription usage Retrieve the current period's usage for a subscription. Authentication: X-Api-Key, or Bearer JWT + X-Api-Key ### Path parameters - `subscriptionId` (`string`, required) — 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. Type: [Usage](/api-reference/models.md#models/Usage) #### 400 The request was malformed or invalid. Type: [Error](/api-reference/models.md#models/Error) #### 401 Authentication is required to access this resource. Type: [Error](/api-reference/models.md#models/Error) #### 403 Access to this resource is forbidden. Type: [Error](/api-reference/models.md#models/Error) #### 404 The requested resource was not found. Type: [Error](/api-reference/models.md#models/Error) #### 500 An unexpected error occurred on the server. Type: [Error](/api-reference/models.md#models/Error) ### Example request ```bash curl https://apiv2.example.com/api/v2/subscriptions/SUBSCRIPTION_ID/usage \ --header 'Authorization: Bearer YOUR_ACCESS_TOKEN' \ --header 'X-Api-Key: YOUR_API_KEY' ``` ## [GET /subscriptions/usage](/api-reference/subscription-usage#tag/subscription-usage/GET/subscriptions/usage) Get usage for multiple subscriptions Retrieve current usage statistics for multiple subscriptions by providing their IDs. Authentication: X-Api-Key, or Bearer JWT + X-Api-Key ### Query parameters - `subscriptionIds` (`array of string`, required, min items 1, max items 100) — List of subscription IDs to retrieve usage for. ### Responses #### 200 Usage statistics for the requested subscriptions. Type: `object` - `items` (`array of object`, required) — Usage information for each requested subscription. - `subscriptionId` (`string`, required, example 123e4567-e89b-12d3-a456-426614174000) — The unique identifier for the subscription. - `usage` (`object`, required) — 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. - `voice` (`object`, optional) — 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). - `national` (`array of UsageVoicePackage`, optional) — Allowance buckets for calls made within the home country, including the base plan's voice allowance and any add-on packages. - `subscriptionAddonId` (`string`, optional, example f47ac10b-58cc-4372-a567-0e02b2c3d479) — 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. - `name` (`string`, required, example Unlimited National) — Human-readable name of the package, as shown to end users. - `callSeconds` (`integer`, required, int64, example 3600) — Call time consumed from this allowance so far, in seconds. - `callCount` (`integer`, required, int64, example 15) — Number of calls placed against this allowance. - `callRemainingSeconds` (`integer`, required, int64, example 32400) — Call time still available in this allowance, in seconds. - `callTotalSeconds` (`integer`, required, int64, example 36000) — The full call time allowance of this package, in seconds. - `status` (`enum`, required, one of ACTIVE, NOT_ACTIVE, EXPIRED) — 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 - `validFrom` (`string`, optional, date-time, example 2025-01-01T00:00:00Z) — Start of the period this allowance applies to. - `validTo` (`string`, optional, date-time, example 2025-02-01T00:00:00Z) — 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. - `metadata` (`object with string keys`, optional) — 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. - `*` (`string`, optional) - `roaming` (`array of UsageVoicePackage`, optional) — Allowance buckets for calls made while roaming abroad. - `subscriptionAddonId` (`string`, optional, example f47ac10b-58cc-4372-a567-0e02b2c3d479) — 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. - `name` (`string`, required, example Unlimited National) — Human-readable name of the package, as shown to end users. - `callSeconds` (`integer`, required, int64, example 3600) — Call time consumed from this allowance so far, in seconds. - `callCount` (`integer`, required, int64, example 15) — Number of calls placed against this allowance. - `callRemainingSeconds` (`integer`, required, int64, example 32400) — Call time still available in this allowance, in seconds. - `callTotalSeconds` (`integer`, required, int64, example 36000) — The full call time allowance of this package, in seconds. - `status` (`enum`, required, one of ACTIVE, NOT_ACTIVE, EXPIRED) — 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 - `validFrom` (`string`, optional, date-time, example 2025-01-01T00:00:00Z) — Start of the period this allowance applies to. - `validTo` (`string`, optional, date-time, example 2025-02-01T00:00:00Z) — 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. - `metadata` (`object with string keys`, optional) — 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. - `*` (`string`, optional) - `ild` (`array of UsageVoiceIldPackage`, optional) — International long distance (ILD) balances for calls placed from the home country to foreign numbers. Tracked as a monetary balance rather than minutes. - `subscriptionAddonId` (`string`, optional, example f47ac10b-58cc-4372-a567-0e02b2c3d479) — The subscription add-on that granted this balance. Present only when the balance comes from an add-on. - `name` (`string`, required, example ILD Top-up) — Human-readable name of the package, as shown to end users. - `balanceMinor` (`integer`, optional, int64, example 1550) — 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. - `currency` (`string`, optional, example USD) — Three-letter ISO 4217 code for the currency the balance is denominated in. Matches the subscription's billing currency. - `expiryDate` (`string`, optional, date, example 2025-12-31) — The date the remaining balance expires and can no longer be used. Absent when the balance does not expire. - `metadata` (`object with string keys`, optional) — 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. - `*` (`string`, optional) - `sms` (`object`, optional) — 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). - `national` (`array of UsageSmsPackage`, optional) — Allowance buckets for messages sent within the home country, including the base plan's SMS allowance and any add-on packages. - `subscriptionAddonId` (`string`, optional, example f47ac10b-58cc-4372-a567-0e02b2c3d479) — 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. - `name` (`string`, required, example 500 SMS National) — Human-readable name of the package, as shown to end users. - `smsCount` (`integer`, required, int64, example 25) — Number of messages consumed from this allowance so far. - `smsRemaining` (`integer`, required, int64, example 475) — Number of messages still available in this allowance. - `smsTotal` (`integer`, required, int64, example 500) — The full message allowance of this package. - `status` (`enum`, required, one of ACTIVE, NOT_ACTIVE, EXPIRED) — 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 - `validFrom` (`string`, optional, date-time, example 2025-01-01T00:00:00Z) — Start of the period this allowance applies to. - `validTo` (`string`, optional, date-time, example 2025-02-01T00:00:00Z) — 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. - `metadata` (`object with string keys`, optional) — 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. - `*` (`string`, optional) - `roaming` (`array of UsageSmsPackage`, optional) — Allowance buckets for messages sent while roaming abroad. - `subscriptionAddonId` (`string`, optional, example f47ac10b-58cc-4372-a567-0e02b2c3d479) — 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. - `name` (`string`, required, example 500 SMS National) — Human-readable name of the package, as shown to end users. - `smsCount` (`integer`, required, int64, example 25) — Number of messages consumed from this allowance so far. - `smsRemaining` (`integer`, required, int64, example 475) — Number of messages still available in this allowance. - `smsTotal` (`integer`, required, int64, example 500) — The full message allowance of this package. - `status` (`enum`, required, one of ACTIVE, NOT_ACTIVE, EXPIRED) — 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 - `validFrom` (`string`, optional, date-time, example 2025-01-01T00:00:00Z) — Start of the period this allowance applies to. - `validTo` (`string`, optional, date-time, example 2025-02-01T00:00:00Z) — 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. - `metadata` (`object with string keys`, optional) — 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. - `*` (`string`, optional) - `ild` (`array of UsageSmsPackage`, optional) — Allowance buckets for messages sent from the home country to foreign numbers (international long distance). - `subscriptionAddonId` (`string`, optional, example f47ac10b-58cc-4372-a567-0e02b2c3d479) — 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. - `name` (`string`, required, example 500 SMS National) — Human-readable name of the package, as shown to end users. - `smsCount` (`integer`, required, int64, example 25) — Number of messages consumed from this allowance so far. - `smsRemaining` (`integer`, required, int64, example 475) — Number of messages still available in this allowance. - `smsTotal` (`integer`, required, int64, example 500) — The full message allowance of this package. - `status` (`enum`, required, one of ACTIVE, NOT_ACTIVE, EXPIRED) — 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 - `validFrom` (`string`, optional, date-time, example 2025-01-01T00:00:00Z) — Start of the period this allowance applies to. - `validTo` (`string`, optional, date-time, example 2025-02-01T00:00:00Z) — 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. - `metadata` (`object with string keys`, optional) — 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. - `*` (`string`, optional) - `mms` (`object`, optional) — 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). - `national` (`array of UsageMmsPackage`, optional) — Allowance buckets for multimedia messages sent within the home country, including the base plan's MMS allowance and any add-on packages. - `subscriptionAddonId` (`string`, optional, example f47ac10b-58cc-4372-a567-0e02b2c3d479) — 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. - `name` (`string`, required, example 100 MMS National) — Human-readable name of the package, as shown to end users. - `mmsCount` (`integer`, required, int64, example 10) — Number of multimedia messages consumed from this allowance so far. - `mmsRemaining` (`integer`, required, int64, example 90) — Number of multimedia messages still available in this allowance. - `mmsTotal` (`integer`, required, int64, example 100) — The full multimedia message allowance of this package. - `validFrom` (`string`, optional, date-time, example 2025-01-01T00:00:00Z) — Start of the period this allowance applies to. - `validTo` (`string`, optional, date-time, example 2025-02-01T00:00:00Z) — 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. - `metadata` (`object with string keys`, optional) — 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. - `*` (`string`, optional) - `roaming` (`array of UsageMmsPackage`, optional) — Allowance buckets for multimedia messages sent while roaming abroad. - `subscriptionAddonId` (`string`, optional, example f47ac10b-58cc-4372-a567-0e02b2c3d479) — 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. - `name` (`string`, required, example 100 MMS National) — Human-readable name of the package, as shown to end users. - `mmsCount` (`integer`, required, int64, example 10) — Number of multimedia messages consumed from this allowance so far. - `mmsRemaining` (`integer`, required, int64, example 90) — Number of multimedia messages still available in this allowance. - `mmsTotal` (`integer`, required, int64, example 100) — The full multimedia message allowance of this package. - `validFrom` (`string`, optional, date-time, example 2025-01-01T00:00:00Z) — Start of the period this allowance applies to. - `validTo` (`string`, optional, date-time, example 2025-02-01T00:00:00Z) — 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. - `metadata` (`object with string keys`, optional) — 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. - `*` (`string`, optional) - `ild` (`array of UsageMmsPackage`, optional) — Allowance buckets for multimedia messages sent from the home country to foreign numbers (international long distance). - `subscriptionAddonId` (`string`, optional, example f47ac10b-58cc-4372-a567-0e02b2c3d479) — 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. - `name` (`string`, required, example 100 MMS National) — Human-readable name of the package, as shown to end users. - `mmsCount` (`integer`, required, int64, example 10) — Number of multimedia messages consumed from this allowance so far. - `mmsRemaining` (`integer`, required, int64, example 90) — Number of multimedia messages still available in this allowance. - `mmsTotal` (`integer`, required, int64, example 100) — The full multimedia message allowance of this package. - `validFrom` (`string`, optional, date-time, example 2025-01-01T00:00:00Z) — Start of the period this allowance applies to. - `validTo` (`string`, optional, date-time, example 2025-02-01T00:00:00Z) — 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. - `metadata` (`object with string keys`, optional) — 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. - `*` (`string`, optional) - `data` (`object`, optional) — 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). - `national` (`array of UsageDataNationalPackage`, optional) — Allowance buckets for data used in the home country, including the base plan's data allowance and any add-on packages. - `subscriptionAddonId` (`string`, optional, example f47ac10b-58cc-4372-a567-0e02b2c3d479) — 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. - `name` (`string`, required, example 10GB National) — Human-readable name of the package, as shown to end users. - `dataBytesUsed` (`integer`, required, int64, example 3221225472) — Data consumed from this allowance so far, in bytes. - `dataBytesRemaining` (`integer`, required, int64, example 7516192768) — Data still available in this allowance, in bytes. - `dataBytesTotal` (`integer`, required, int64, example 10737418240) — The full data allowance of this package, in bytes. - `rlahBytesUsed` (`integer`, optional, int64, example 1073741824) — Data consumed while roaming under RLAH (Roam Like At Home) rules, in bytes. Present only when the package includes an RLAH allowance. - `rlahBytesRemaining` (`integer`, optional, int64, example 4294967296) — RLAH data still available, in bytes. Once exhausted, roaming usage may incur additional charges even though national data remains. - `rlahBytesTotal` (`integer`, optional, int64, example 5368709120) — The portion of this package usable while roaming under RLAH rules, in bytes. Often lower than the full national allowance. - `status` (`enum`, required, one of ACTIVE, NOT_ACTIVE, EXPIRED) — 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 - `validFrom` (`string`, optional, date-time, example 2025-01-01T00:00:00Z) — Start of the period this allowance applies to. - `validTo` (`string`, optional, date-time, example 2025-02-01T00:00:00Z) — 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. - `metadata` (`object with string keys`, optional) — 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. - `*` (`string`, optional) - `roaming` (`array of UsageDataRoamingPackage`, optional) — Allowance buckets for data used while roaming abroad, from the base plan's roaming allowance or dedicated roaming add-on packages. - `subscriptionAddonId` (`string`, optional, example f47ac10b-58cc-4372-a567-0e02b2c3d479) — 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. - `name` (`string`, required, example Asia 5GB Roaming) — Human-readable name of the package, as shown to end users. - `dataBytesUsed` (`integer`, required, int64, example 1073741824) — Data consumed from this allowance so far, in bytes. - `dataBytesRemaining` (`integer`, required, int64, example 4294967296) — Data still available in this allowance, in bytes. - `dataBytesTotal` (`integer`, required, int64, example 5368709120) — The full data allowance of this package, in bytes. - `status` (`enum`, required, one of ACTIVE, NOT_ACTIVE, EXPIRED) — 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 - `validFrom` (`string`, optional, date-time, example 2025-01-01T00:00:00Z) — Start of the period this allowance applies to. - `validTo` (`string`, optional, date-time, example 2025-02-01T00:00:00Z) — 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. - `metadata` (`object with string keys`, optional) — 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. - `*` (`string`, optional) - `updatedAt` (`string`, required, date-time, example 2024-01-15T10:30:00Z) — 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. Type: [Error](/api-reference/models.md#models/Error) #### 401 Authentication is required to access this resource. Type: [Error](/api-reference/models.md#models/Error) #### 403 Access to this resource is forbidden. Type: [Error](/api-reference/models.md#models/Error) #### 404 The requested resource was not found. Type: [Error](/api-reference/models.md#models/Error) #### 500 An unexpected error occurred on the server. Type: [Error](/api-reference/models.md#models/Error) ### Example request ```bash 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' ```