POST /devices/usage/actions/list/aggregate
Returns the total amount of data sent and the total number of SMS messages sent or received by a set of devices in a specified time frame (one month maximum). The information is returned in a callback response, so you must register a URL for DeviceUsage callback messages.
See also:
Retrieve Device Usage History
Retrieve Device Connection History
Retrieve Device Provisioning History
The ThingSpace Platform calculates three types of usage data: data usage, SMS usage, and rated usage. These usage data types originate from the following sources:
POST https://thingspace.verizon.com/api/m2m/v1/devices/usage/actions/list/aggregate
None.
The request header must contain the current session token.
Parameter Name | Data Type | Description |
---|---|---|
VZ-M2M-Token required |
string | A valid session token returned by POST /session/login. |
The request body identifies the device and reporting period that you want included in the report.
Parameter Name | Data Type | Description |
---|---|---|
deviceIds optional* |
array of deviceId objects | One or more devices for which you want aggregated data, specified by device ID. |
kind, id required for devicesIds |
string | The type and value of the device identifier.
|
accountName optional* |
string | The name of a billing account. This value is required if you specified groupName. To retrieve the aggregate device usage for all devices associated with a billing account, specify the AccountName without specifying either DeviceList or groupName. An account name is usually numeric, and must include any leading zeros. |
groupName optional* |
string | The name of a device group, if you want to only include devices in that group. |
startTime required |
string | The beginning of the reporting period. The startTime cannot be more than 6 months before the current date. |
endTime required |
string | The end of the reporting period. The endTime date must be within on month of the startTime date. |
Get a one month aggregated report for two devices:
{
"deviceIds": [
{
"id": "990005350342573",
"kind": "imei"
},
{
"id": "A10085E5003861",
"kind": "meid"
}
],
"endTime": "2017-12-30T00:00:00-05:00",
"startTime": "2017-12-01T00:00:00-05:00"
}
Status 200
Parameter Name | Data Type | Description |
---|---|---|
requestId | string | A unique string that associates the request with the results that are sent via a callback service. A single callback can contain information for up to 2000 devices. For requests that contain more than 2000 devices, the ThingSpace Platform will send multiple callbacks, each containing data for up to 2000 devices, until all data is sent. The Platform will send a final callback with the message, “Request Completed Processing” after the last callback containing data. All callbacks will have the same RequestId. |
{
"requestId": "595f5c44-c31c-4552-8670-020a1545a84d"
}
Callback for an individual device:
{
"requestId": "e931b605-6e9d-48d5-9587-59e3b2c3d3d6",
"deviceResponse": {
"usageResponse": [
{
"deviceIds": [
{
"id": "356075050085705",
"kind": "IMEI"
}
],
"dataUsage": "448751",
"smsUsage": "0",
"startDate": "2017-12-01T11:30:09.0000000+00:00",
"endDate": "2017-12-29T11:30:09.0000000+00:00"
}
]
}
}
Callback for a group of devices:
{
"requestId": "2324c7c3-a126-408b-aa2a-a002d62814c1",
"deviceResponse": {
"usageResponse": [
{
"deviceIds": [
{
"id": "7322532728",
"kind": "Mdn"
},
{
"id": "A10000458D70D6",
"kind": "Meid"
}
],
"dataUsage": "0",
"smsUsage": "0",
"startDate": "2016-08-02T00:00:00.0000000+00:00",
"endDate": "2016-08-31T00:00:00.0000000+00:00"
},
{
"deviceIds": [
{
"id": "7322583147",
"kind": "Mdn"
},
{
"id": "311480039150901",
"kind": "Imsi"
},
{
"id": "89148000000385464152",
"kind": "Iccid"
},
{
"id": "356075050085705",
"kind": "Imei"
},
{
"id": "17322583147",
"kind": "Msisdn"
}
],
"dataUsage": "448751",
"smsUsage": "0",
"startDate": "2016-08-02T00:00:00.0000000+00:00",
"endDate": "2016-08-31T00:00:00.0000000+00:00"
},
{
"deviceIds": [
{
"id": "2016024390",
"kind": "Mdn"
},
{
"id": "311480115324693",
"kind": "Imsi"
},
{
"id": "89148000001134816700",
"kind": "Iccid"
},
{
"id": "990000581973932",
"kind": "Imei"
},
{
"id": "12016024390",
"kind": "Msisdn"
}
],
"dataUsage": "2666339",
"smsUsage": "0",
"startDate": "2016-08-02T00:00:00.0000000+00:00",
"endDate": "2016-08-31T00:00:00.0000000+00:00"
}
]
}
}
Request completed callback:
{
"requestId": "e931b605-6e9d-48d5-9587-59e3b2c3d3d6",
"deviceResponse": {
"usageResponse": []
},
"comment": "Request Completed Processing"
}
Status 400
All error messages are returned in this format:
{
"errorCode": "error code string",
"errorMessage": "error message string"
}
Error codes and messages are listed on the Error Messages page, along with explanations and suggestions for corrective actions.
Try It Out!