Query Usage
Purpose
Returns the latest known usage values for a specified SIM for the current calendar month.
The response includes:
- Data usage
- SMS usage
- Voice usage
The returned values are generally current to within the last few hours.
The target SIM is specified using the <iccid> element.
Returned Values
The response includes the following elements:
- <data-mb> — Data usage in megabytes (MB)
- <sms> — Total chargeable SMS (SMS MO, SMS MOIP and SMS MT)
- <voice-mins> — Voice usage in minutes, rounded up to the next whole minute
Usage Guidance
This query may involve onward API calls to service provider partners.
As a result:
- It is relatively resource intensive
- It may be subject to request rate limits
This query is not intended to provide real-time, minute-by-minute usage updates.
It should not be used as a high-frequency polling mechanism, particularly for large SIM populations.
If your use case requires frequent usage monitoring, please discuss your requirements with support before implementation.
Endpoint
POST https://api.m2miportal.com
Content-Type: application/xml
Accept: application/xml
Request (XML)
<query-usage version="1" api-id="123456">
<authentication>
<username>username</username>
<password>password</password>
</authentication>
<iccid>1234567890123456789</iccid>
</query-usage>Response (Success)
<query-usage-response api-id="123456">
<api-outcome>Success</api-outcome>
<data-mb>80.010</data-mb>
<sms>5</sms>
<voice-mins>31</voice-mins>
</query-usage-response>Response (Failure)
If a request cannot be processed, the response will include:
- api-outcome indicating failure
- An error description explaining the reason
Failure responses may occur due to:
- Invalid authentication credentials
- Invalid or unknown identifiers (for example ICCID or MSISDN)
- Invalid or missing parameters
- Values not permitted for the specified SIM type or account configuration
- Insufficient permissions
Integrating systems should validate input data before submission and implement appropriate error handling and logging.