Search for subscriptions:

POST /subscriptions/actions/query

Search for subscriptions by property values. Returns an array of all matching subscription resources.

See also:
Create a subscription
Update a subscription
Delete a subscription

Uses and Requirements

Request Components

HTTP Request


Resource Path and Query Parameters


Header Parameters

The request header must contain a current ThingSpace authorization token and a current VZ-M2M session token, and must set the content-type to JSON.


Property Name Data Type Description
string HTTP Authorization request header containing a valid ThingSpace Bearer token.
string A valid session token returned by a Connectivity Management API POST /session/login request using the account’s UWS credentials.
string Must be application/json.

Request Body

The request body specifies fields and values to match.

Property Name Data Type Description
JSON object The ID of the authenticating billing account, in the format {"billingaccountid":"1234567890-12345"}.
JSON object A comma-separated list of properties and comparator values to match against subscriptions in the ThingSpace account. If the request does not include $selection, the response will include all subscriptions to which the requesting user has access.

Example Request

Find a subscription by its UUID

curl -X POST \
  -H 'Authorization: Bearer 506be090c32836bad23e1bcbbe829820' \
  -H 'VZ-M2M-Token: 87734bdb-9c00-4f9a-96f1-d2cc800624b8' \
  -H 'Content-Type: application/json' \
  -d '{
    "accountidentifier": {"billingaccountid":"1223334444-00001"},
    "resourceidentifier": {"id": "dd1682d3-2d80-cefc-f3ee-25154800beff"}

Find all subscription that have configuration failures

curl -X POST \
  -H 'Authorization: Bearer 506be090c32836bad23e1bcbbe829820' \
  -H 'VZ-M2M-Token: 87734bdb-9c00-4f9a-96f1-d2cc800624b8' \
  -H 'Content-Type: application/json' \
  -d '{
    "accountidentifier": {"billingaccountid":"1223334444-00001"},
    "$selection": {"configurationfailures gt": 0 }

Success Responses

Status 200

A success response includes an array of all matching subscriptions. Each subscription includes the full subscription resource definition.

Property Name Data Type Description
configurationfailures integer The number of streaming failures due to faulty configuration.
createdon string, date-time The date the resource was created.
delegateid string Not currently used.
description string Description of the subscription.
disabled boolean Whether the subscription is currently sending data.
email string The address to which any error reports should be delivered.
filter string Filter for events.
groupid string ID of a tag resource for group-level streaming.
id string, UUID ThingSpace unique ID for the subscription that was created.
kind string Identifies the resource kind.
laststreamingstatus string Success or fail
laststreamingtime string, date-time The date and time that the last stream send was attempted.
lastupdated string, date-time The date the resource was last updated.
name string Name of the subscription.
networkfailures integer The number of failures due to network problems.
streamfailures integer  
streamkind string, enum The event type that will be sent in the data stream.
targetid string Target to be used for dispatching events.
targettype string  
version string, UUID Version of the underlying schema resource.
versionid string, UUID The version of the resource.

Example Success Response

    "configurationfailures": 0,
    "createdon": "2019-02-13T23:13:24.689Z",
    "delegateid": "00000000-0000-0000-0000-000000000000",
    "disabled": false,
    "email": "",
    "id": "98015aed-e984-62be-f049-1d895d2d1812",
    "kind": "ts.subscription",
    "laststreamingstatus": "success",
    "laststreamingtime": "2019-02-20T18:20:45.865Z",
    "lastupdated": "2019-02-13T23:13:24.689Z",
    "networkfailures": 0,
    "streamfailures": 0,
    "streamkind": "ts.event",
    "targetid": "4e112cb3-da1d-6ece-f2c6-bb8700b20b09",
    "targettype": "Amazon Web Services",
    "version": "1.0",
    "versionid": "f68b8862-2fe4-11e9-85fd-02420a4c170d"

Failure Responses

Status 4xx

All error messages are returned in this format:

  "error": "error code string",
  "error_description": "error message string",
  "cause": "further explanation"

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