Retrieve Device Usage History

Retrieve Device Usage History:
POST /devices/usage/actions/list

Returns the daily network data usage of a single device during a specified time period.

Contents

See also:
Retrieve Device Connection History
Retrieve Device Provisioning 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.

About Data Usage Calculations

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, 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.

Parameter Name Data Type Description
deviceId
required
deviceId object An identifier for a single device.
kind,
id

required
strings 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
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

{
  "deviceId": {
    "id": "89141390780800784259",
    "kind": "iccid"
  },
  "earliest": "2018-05-01T00:00:01Z",
  "latest": "2018-06-01T00:00:01Z"
}

Success Responses

Status 200 or 202

Returns an array of device usage events.

Parameter Name Data Type Description
timestamp dateTime The date of the recorded usage.
servicePlan string The service plan in effect on the report date.
bytesUsed int64 The number of bytes that the device sent or received on the report date.
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.
extendedAttributes array The number of mobile-originated and mobile-terminated SMS messages on the report date.
key string The key for an extended attribute.
value string The value for an extended attribute.
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.

Example Success Response

{
  "usageHistory":[
    {
      "bytesUsed": 0,
      "extendedAttributes": [
        {
          "key": "MoSms",
          "value": "0"
        },
        {
          "key": "MtSms",
          "value": "1"
        }
      ],
      "servicePlan": "Tablet5GB",
      "smsUsed": 1,
      "source": null,
      "timestamp": "2018-05-16T19:00:00-05:00"
    },
    {
      "bytesUsed": 419281216,
      "extendedAttributes": [
        {
          "key": "MoSms",
          "value": "0"
        },
        {
          "key": "MtSms",
          "value": "0"
        }
      ],
      "servicePlan": "Tablet5GB",
      "smsUsed": 0,
      "source": null,
      "timestamp": "2018-05-17T19:00:00-05:00"
    },
    {
      "bytesUsed": 582018,
      "extendedAttributes": [
        {
          "key": "MoSms",
          "value": "0"
        },
        {
          "key": "MtSms",
          "value": "0"
        }
      ],
      "servicePlan": "Tablet5GB",
      "smsUsed": 0,
      "source": null,
      "timestamp": "2018-05-18T19:00:00-05:00"
    },
    {
      "bytesUsed": 0,
      "extendedAttributes": [
        {
          "key": "MoSms",
          "value": "0"
        },
        {
          "key": "MtSms",
          "value": "0"
        }
      ],
      "servicePlan": "Tablet5GB",
      "smsUsed": 0,
      "source": null,
      "timestamp": "2018-05-19T19:00:00-05:00"
    }
  ],
  "hasMoreData": false
}

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!