Get Diagnostics Subscription

Get an Account’s Diagnostics Subscription Status:
GET /subscriptions?accountName={account}

The API returns the Bundle SKU name TS-BUNDLE-KTO-DIAGNOSTIC-MRC which is the SKU necessary to perform live RF streaming. A single bundle SKU license provides a maximum base allowance of observation of B*M where B=6000 events and M is the number of streamable attributes (currently there are 4 streamable attributes) events in a single month for an account. If N licenses are purchased then the total allowance is N*B*M.

For example, if there are 100 devices in an account, the customer may purchase a 100 licenses of the bundle SKU giving him a total observation events allowance of 100*6000*4 = 2,400,000 events. A single monitoring event corresponds to a callback received in response to a Start Diagnostics Observation API.

N = Number of bundle licenses purchased
B = Base allowance (B=6000 monitoring events)
M = Number of Streamable Diagnostics attributes (M=4)

Total monthly allowance = N*B*M

Contents

Uses and Requirements

Thingspace Services Subscriptions provide access to certain services offered by Thingspace, including Location, Software Management, Security and Diagnostics. While basic features, such as a Data plan or an SMS plan are necessary for device connectivity and operation, Services Subscriptions are a value-added option that must be purchased in addition to connectivity plans. The following Subscription-based restrictions exist for access to Diagnostics:

  • For RF quality information and live streaming, a Bundled Services Subscription must be added to the customer account to which the device is billed. Also, the RF communications module used by the device must be certified for LwM2M diagnostics through the Verizon Open Development certification program. Certification for LwM2M diagnostics is now mandatory for communications modules being submitted for Verizon certification. For example, most modules that support LTE CAT M communications do support the LwM2M protocol.
  • For device Location information, a Location Services Subscription or a Bundled Services subscription must be added to the customer account to which the device is billed.
  • For device Software version information as well as to update device software, a Software Management subscription or a Bundled Services subscription must be added to the customer account to which the device is billed.

Diagnostics APIs not needing any Subscription:

  • Get Device Diagnostic Information
  • Get Device Extended Diagnostic Information

Diagnostics APIs needing a Subscription: A Bundle Subscription is needed for the following APIs that are used for the RF Live Streaming features:

  • Get Diagnostics Subscriptions
  • Start Diagnostics Observation
  • Stop Diagnostics Observation
  • Get Diagnostics History Data
  • Get Diagnostics Settings
  • Register Diagnostics Callbacks
  • List Diagnostics Callback
  • Delete Diagnostics Callback

Request Components

HTTP Request

GET https://thingspace.verizon.com/api/diagnostics/v1/subscriptions?accountName={account}

Resource Path and Query Parameters

You must include the account name in the path.

Parameter Name Data Type Description
accountName
required
string The name of the account for which you want the Diagnostic Services subscription status. An account name is usually numeric, and must include any leading zeros.

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 /api/m2m/v1/session/login.
Content-Type
required
string Must be application/json.

Request Body

None.

Success Responses

Status 200
A success response contains the current status of the report.

Parameter Name Data Type Description
accountName string The name of the account for which you want the Diagnostic Services subscription status. An account name is usually numeric, and must include any leading zeros.
skuName string The name of the sku for which the subscription information is being requested.
totalAllowed integer($int32) The total number of reports allowed per month for this account.
totalUsed integer($int32) The total number of reports used this month for this account.
createdOn string($date-time) The date and time of when this subscription was created.
lastUpdated string($date-time) The date and time of when this subscription was last updated.

Example Success Response

Subscription {
  "accountName":   "TestQAAccount",
  "skuName":       "TS-BUNDLE-KTO-DIAGNOSTIC-MRC",
  "totalAllowed":  100,
  "totalUsed":     50,
  "createdOn":     "2019-08-29T00:47:59.240Z",
  "lastUpdated":   "2019-08-29T00:47:59.240Z"
}

Failure Responses

Status 400 All error messages are returned in this format:

{
  "errorCode": "The type of error, such as INVALID_REQUEST.",
  "errorMessage": "Additional error information."
}

Error codes and messages are listed on the Error Codes page, along with explanations and suggestions for corrective actions.

Try It Out!