Retrieve Aggregate Usage

POST /devices/usage/actions/list/aggregate

This endpoint retrieves an aggregate, or summary, of usage for the device specified.

Contents

Request Components

Header Parameters

The request header must set the content-type to JSON, contain a current ThingSpace authorization token and a current VZ-M2M session token. For more details on how to get these tokens, visit  Getting Started.

Parameter Name Data Type Description
Authorization
required		 string

HTTP Authorization bearer token:
Authorization: Bearer {token}
VZ-M2M-Token
required		 string

A valid session token:
VZ-M2M-Token: {M2Mtoken}
Content-Type
required		 string

Must be application/json:
Content-Type: application/json

HTTP Request

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

Request Parameters

Parameter Data Type Description

deviceIds
required

 array

The device ID value
   id
 string The numeric value of the device ID type.
   kind
 string

The type of device ID represented by the ID value. Only the following are supported by the request and both values must be present:

  • eid - Electronic ID, a 32-digit unique ID of the device

NOTE: for this query, only EID is valid.
accountName
required		 string The numeric name of the account. This is in the format "0000123456-00001". Leading zeros must be included.
startTime
required		 string ($datetime) The start of the time period requested.
endTime
required		 string ($datetime) The end of the time period requested.

Request Body

Example request:

{
    "deviceIds": [
        {
            "id": "32-digit EID",
            "kind": "eid"
        }
    ],
    "accountName": "0000123456-00001",
    "startTime": "2023-10-01T00:00:00Z",
    "endTime": "2023-10-30T00:00:00Z"
}

Success Response

Status 200

A successful response shows a system generated request ID to track the request.

Example Response:

{
  "requestId": "d1f08526-5443-4054-9a29-4456490ea9f8"
}

Callback Response

These endpoints send responses asynchronously. In order to read the results a callback is required. To learn more about callbacks, please visit About Callback Services.

Example callback responses:

{
  "requestId": "d1f08526-5443-4054-9a29-4456490ea9f8",
  "deviceResponse": {
    "usageResponse": [
      {
        "deviceIds": [
          {
            "id": "32-digit EID",
            "kind": "eid"
          }
        ],
        "dataUsage": "245971989",
        "smsUsage": "6",
        "startDate": "2023-10-01T00:00:00.0000000+00:00",
        "endDate": "2023-10-30T00:00:00.0000000+00:00",
        "moSms": "5",
        "mtSms": "1"
      }
    ]
  },
  "callbackCount": 1,
  "maxCallbackThreshold": 4
}

Callback Parameters

Parameter Data Type Description
requestId string The requestId being viewed. This is a system generated value from the request above.
deviceResponse object Contains the response from the device queried.
    usageResponse array The record of usage from the device queried.
        deviceIds
 array

An array of devices being queried by the request. Each deviceId will contain:

  • id
  • kind
            id
 string The numeric value of the device ID.
            kind
 string

The type of device ID represented by the ID value:

  • eid - 32-digit Electronic ID
        dataUsage string The total amount of data used (in Bytes) for that time period..
        smsUsage string The total number of SMS (text) messages sent and received
        startDate string ($datetime) The starting point of the time period queried.
        endDate string ($datetime) The ending point of the time period queried.
        moSms string Mobile Originating SMS. Text messages sent.
        mtSms string Mobile Terminating SMS. Text messages received.
callbackCount string The number of responses for deviceResponse found.
maxCallbackThreshold string The maximum number of responses for deviceResponse allowed.

Failure Responses

All error responses will be in the following format

{
  "errorCode": "The 3-digit HTML error code",
  "errorMessage": "string"
}