Retrieve Aggregate Device Usage History

Retrieve Aggregate Device Usage History:

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.

Contents

See also:
Retrieve Device Usage History
Retrieve Device Connection History
Retrieve Device Provisioning History

Uses and Requirements

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:

  • 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, the ThingSpace Platform updates usage estimates 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.

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.

Request Components

HTTP Request

POST https://thingspace.verizon.com/api/m2m/v1/devices/usage/actions/list/aggregate

Resource and 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, 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.
  • ESN - decimal, 11 digits
  • EID - decimal, up to 32 digits
  • ICCID - decimal, up to 20 digits
  • IMEI - decimal, up to 15 digits
  • MDN - decimal, 10 digits
  • MEID - hexadecimal, 14 characters
  • MSISDN - decimal, 11 digits
 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.

Example Request Body

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"
}

Success Responses

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.

Example Success Response

{
  "requestId": "1631e200-7398-4609-b1f8-398341229176"
}

Callback Response Parameters

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:
  • ESN (11 digits)
  • EID (up to 32 digits)
  • ICCID (up to 20 digits)
  • IMEI (up to 16 digits)
  • MDN (10 digits)
  • MEID (14 characters, hexadecimal)
  • MSISDN (11 digits)
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.

Example Success Callback Response

{
    "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"
}

Failure Responses

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!