POST /devices/usage/actions/list/aggregateReturns 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 various types of usage data: data usage, SMS usage, and rated usage. For RTR customers, domestic usage and international usage may also be returned. These usage data types originate from the following sources:
You can retrieve device usage using either a device identifer, or a label, but not both. To retrieve usage data using a label, you must first associate a label with a device, as described in Set Usage Segmentation Labels API.
POST https://thingspace.verizon.com/api/m2m/v1/devices/usage/actions/list/aggregate
None.
The request header must contain a current ThingSpace authorization bearer token and a valid VZ-M2M session token, and must set the content-type to JSON.
| Parameter Name | Data Type | Description |
|---|---|---|
| Authorization required |
string | HTTP Authorization bearer token. |
| VZ-M2M-Token required |
string | A valid session token returned by POST /session/login. |
| Content-Type required |
string | Must be application/json. |
The request body identifies the device, or label, and reporting period that you want included in the report.
| Parameter Name | Data Type | Description |
|---|---|---|
| label optional |
array of label identifiers. | Label name and value associated with the device. You can only use label or deviceIds, but not both.If no label or deviceIds are listed in the request, all devices for the account are returned. |
label.name
optional |
varchar(20) | The label name associated with the device. |
label.value
optional |
varchar(50) | The label value. |
| deviceIds optional* |
array of deviceId objects | One or more devices for which you want aggregate data, specified by device ID. You can only use label or deviceIds, but not both.If no label or deviceIds are listed in the request, all devices for the account are returned. |
kind,
id required for devicesIds |
string | The type and value of the device identifier.
|
| accountName * optional **Recommended |
string | The name of a billing account. An account name is usually numeric, and must include any leading zeros. 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. **By coding for the account number today, you prevent future code from breaking if you ever add a new sub-account. |
| 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 an aggregate report for two (or more) devices using device identifiers:
{
"deviceIds": [
{
"id": "84258000000891490087",
"kind": "ICCID"
},
{
"id": "84258000000891490086",
"kind": "ICCID"
}
],
"accountName": "9992330389-00001",
"endTime": "2021-08-30T00:00:00-06:00",
"startTime": "2021-08-01T00:00:00-06:00"
}
Get an aggregate report for one device using device identifiers:
{
"deviceIds": [
{
"id": "84258000000891490087",
"kind": "ICCID"
}
],
"accountName": "9992330389-00001",
"endTime": "2021-08-30T00:00:00-06:00",
"startTime": "2021-08-01T00:00:00-06:00"
}
Get an aggregate report for all the devices on an account:
{
"accountName": "9992330389-00001",
"endTime": "2021-08-31T23:59:59+00:00",
"startTime": "2021-08-01T00:00:01+00:00"
}
Get an aggregate report using the group name:
{
"groupName":"SMS",
"accountName": "9992330389-00001",
"endTime": "2021-08-30T00:00:00-06:00",
"startTime": "2021-08-01T00:00:00-06:00"
}
Get an aggregate report using labels:
{
"labels": [
{
"name": "VIN",
"value": "VINMwertty10"
},
{
"name": "VIN",
"value": "VINMwertty11"
}
],
"accountName": "9992330389-00001",
"endTime": "2020-12-10T00:00:00-05:00",
"startTime": "2020-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 sends multiple callbacks, each containing data for up to 2000 devices, until all data is sent. The Platform sends a final callback with the message, “Request Completed Processing” after the last callback containing data. All callbacks have the same RequestId. |
{
"requestId": "1631e200-7398-4609-b1f8-398341229176"
}
| Parameter | Type | Description |
|---|---|---|
| callbackCount | integer | The number of times this callback message has been sent. |
| deviceResponse | responseObject | Callback response object. |
| deviceResponse.usageResponse | responseObject | Callback response object |
| datausage | string | The sum of all data, in bytes, that the device sent or received during the specified dates. |
| deviceIds | DeviceIdentifier | Array of device identifiers and their values. |
| id | string | The value of the device identifier. |
| kind | string | The type of the device identifier. Valid types of identifiers are:
|
| endDate | dateTime string | The last date in the reporting period, in dateTime format. |
| label | string | Label name and value associated with the device |
| label.name | varchar(20) | The label name associated with the device. For example, VIN. |
| label.value | varchar(50) | The label value. |
| moSms | int | The number of SMS messages sent by the device during the reporting period. |
| mtSms | int | The number of SMS messages sent to the device during the reporting period. |
| smsUsage | int | The sum of all SMS usage by the device during the specified dates. This number includes all SMS messages sent by the device and all acknowledged messages sent to the device. |
| startDate | dateTime string | The first date in the reporting period, in dateTime format. |
| domesticUsage | int | For RTR customers, domestic usage in bytes. |
| internationalUsage | int | For RTR customers, international usage in bytes. |
| maxCallbackThreshold | integer | The maximum number of times this callback message will be sent if it is not correctly acknowledged. |
| 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 sends multiple callbacks, each containing data for up to 2000 devices, until all data is sent. The Platform sends a final callback with the message, “Request Completed Processing” after the last callback containing data. All callbacks have the same RequestId. |
{
"callbackCount": 1,
"deviceResponse": {
"usageResponse": [
{
"dataUsage": "4096",
"deviceIds": [
{
"id": "19740048979615732358200659283985",
"kind": "EID"
}
],
"endDate": "2020-12-10T00:00:01.0000000",
"label": {
"name": "VIN",
"value": "VINMwertty10"
},
"moSms": "0",
"mtSms": "0",
"smsUsage": "0",
"startDate": "2020-12-01T00:00:01.0000000"
},
{
"dataUsage": "4096",
"deviceIds": [
{
"id": "79050184256491299168383635409505",
"kind": "EID"
}
],
"endDate": "2020-12-10T00:00:01.0000000",
"label": {
"name": "VIN",
"value": "VINMwertty11"
},
"moSms": "0",
"mtSms": "0",
"smsUsage": "0",
"domesticUsage": "2048",
"internationalUsage": "2048",
"startDate": "2020-12-01T00:00:01.0000000"
}
]
},
"maxCallbackThreshold": 4,
"requestId": "1631e200-7398-4609-b1f8-398341229176"
}
Request completed processing callback:
{
"requestId": "1631e200-7398-4609-b1f8-398341229176",
"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.