Retrieve Aggregated Device Usage History

Retrieve Aggregated Device Usage Data:
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 three types of usage data: data usage, SMS usage, and rated usage. 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.

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 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.
  • ESN - decimal, 11 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 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"
}

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": "595f5c44-c31c-4552-8670-020a1545a84d"
}

Example Success Callback Response

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 processing callback:

{
  "requestId": "e931b605-6e9d-48d5-9587-59e3b2c3d3d6",
  "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!