API Reference
Retrieve Device Usage History
Uses and Requirements
Each response includes a maximum of 500 records. To obtain more records, you can call the API multiple times, adjusting the earliest value each time to start where the previous request finished.
You can retrieve device usage using a device identifier, or a label associated with the device in the request. If you want to use a label associated with a device in the request, you must first associate a label with a device, as described in Set Usage Segmentation Labels API. About Data Usage Calculations
The ThingSpace Platform calculates three 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:
- The ThingSpace Platform updates data usage estimates in near real time, to within 15 minutes of the end of a device’s last data session. For 4G devices that stay connected for extended periods, usage estimates are updated approximately every 6 hours until the device disconnects.
- The Verizon Enterprise Network updates SMS usage data every 24 hours, with SMS usage accumulated as of 48 hours in the past, for a total maximum delay of three days.
- A Verizon Data Warehouse feed updates rated data and SMS usage daily, with unbilled, non-roaming usage data that is usually two days in arrears. Roaming data may be updated less frequently.
About Date Ranges
There is no date range limit for the Device Usage Report. However, in accordance with ThingSpace Data Retention Policy, the records contained in this report are kept for 12 months. Though you may specify any date range, you will not receive results for records that are older than 12 months.
Requests for date ranges that span many months may time out due to the time required to retrieve records for every day in the reporting period. If a request times out, try sending two or more requests for shorter date ranges to get the equivalent data.
Request Components
HTTP Request
POST https://thingspace.verizon.com/api/m2m/v1/devices/usage/actions/list
Query Parameters
None.
Header Parameters
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. |
Request Body
The request body identifies the device and reporting period that you want included in the report. You can specify a label, or deviceId in the request.
| Parameter Name | Data Type | Description |
|---|---|---|
| label optional | array of label identifiers. | Label name and value associated with the device. |
| label.name optional | varchar(20) | The label name associated with the device. |
| label.value optional | varchar(50) | The label value. |
| deviceId required if not using label | deviceId object | An identifier for a single device. |
| kind, id required for deviceId | strings | The type and value of the device identifier. ESN - decimal, 11 digits ICCID - decimal, up to 20 digits IMEI - decimal, up to 16 digits MDN - decimal, 10 digits MEID - hexadecimal, 14 characters MSISDN - decimal, 11 digits |
| earliest required | string | The earliest date for which you want usage data. |
| latest required | string | The last date for which you want usage data. |
Example Request Body with Device Identifier
{
"deviceId": {
"id": "50684915885088839315521399821675",
"kind": "eid"
},
"earliest": "2018-03-20T00:00:01Z",
"latest": "2020-12-31T00:00:01Z"
}Example Request Body with a Label
{
"label": {
"value": "VINMwertty9",
"name": "VIN"
},
"earliest": "2018-03-20T00:00:01Z",
"latest": "2020-12-31T00:00:01Z"
}Success Responses
Status 200 or 202
Returns a single device usage list response. For RTR customers, the response may include domestic usage and international usage as extended attributes.
| Parameter Name | Data Type | Description |
|---|---|---|
| hasMoreData | boolean | False for a status 200 response. True for a status 202 response, indicating that there is more data to be retrieved. Send another request, adjusting the earliest value in the request based on the timestamp in the last record in the current response. |
| deviceId | deviceId object | An identifier for a single device. |
| kind, id | strings | The type and value of the device identifier. ESN - decimal, 11 digits ICCID - decimal, up to 20 digits IMEI - decimal, up to 16 digits MDN - decimal, 10 digits MEID - hexadecimal, 14 characters MSISDN - decimal, 11 digits |
| usageHistory | response object | placeholder |
| bytesUsed | int64 | The number of bytes that the device sent or received on the report date. |
| extendedAttributes | array | The number of mobile-originated and mobile-terminated SMS messages on the report date. |
| key | string | The key for an extended attribute. In this example, following key attributes are included: MoSms - Number of SMS messages sent by the device during the reporting period. MtSMS - Number of SMS messages sent by the device during the reporting period. domesticUsage - For RTR customers, domestic usage in bytes. internationalUsage - For RTR customers, international usage in bytes. |
| value | string | The value for an extended attribute. |
| smsUsed | int32 | The number of SMS messages that were sent or received on the report date. |
| source | string | The source of the information for the reported usage. |
| timestamp | dateTime | The date of the recorded usage. |
Example Success Response with Device Identifiers
{
"hasMoreData": false,
"deviceId": {
"id": "50684915885088839315521399821675",
"kind": "eid"
},
"usageHistory": [
{
"bytesUsed": 4096,
"extendedAttributes": [
{
"key": "MoSms",
"value": "0"
},
{
"key": "MtSms",
"value": "0"
},
{
"key": "domesticUsage",
"value": "2048"
},
{
"key": "internationalUsage",
"value": "2048"
}
],
"smsUsed": 0,
"source": "Raw Usage",
"timestamp": "2020-12-01T00:00:00Z"
},
{
"bytesUsed": 8192,
"extendedAttributes": [
{
"key": "MoSms",
"value": "0"
},
{
"key": "MtSms",
"value": "0"
},
{
"key": "domesticUsage",
"value": "4096"
},
{
"key": "internationalUsage",
"value": "4096"
}
],
"smsUsed": 0,
"source": "Raw Usage",
"timestamp": "2020-12-02T00:00:00Z"
},
{
"bytesUsed": 4096,
"extendedAttributes": [
{
"key": "MoSms",
"value": "0"
},
{
"key": "MtSms",
"value": "0"
},
{
"key": "domesticUsage",
"value": "2048"
},
{
"key": "internationalUsage",
"value": "2048"
}
],
"smsUsed": 0,
"source": "Raw Usage",
"timestamp": "2020-12-09T00:00:00Z"
}
]
}Example Success Response with a Label
{
"hasMoreData": false,
"deviceId": {
"id": "50684915885088839315521399821675",
"kind": "Eid"
},
"usageHistory": [
{
"bytesUsed": 4096,
"extendedAttributes": [
{
"key": "MoSms",
"value": "0"
},
{
"key": "MtSms",
"value": "0"
}
],
"smsUsed": 0,
"source": "Raw Usage",
"timestamp": "2020-12-01T00:00:00Z"
},
{
"bytesUsed": 8192,
"extendedAttributes": [
{
"key": "MoSms",
"value": "0"
},
{
"key": "MtSms",
"value": "0"
}
],
"smsUsed": 0,
"source": "Raw Usage",
"timestamp": "2020-12-02T00:00:00Z"
},
{
"bytesUsed": 4096,
"extendedAttributes": [
{
"key": "MoSms",
"value": "0"
},
{
"key": "MtSms",
"value": "0"
}
],
"smsUsed": 0,
"source": "Raw Usage",
"timestamp": "2020-12-09T00:00:00Z"
}
]
}