Search Device Fields:

`POST /devices/fields/actions/history/search`

Search device event history to find events that match criteria. Sensor readings, configuration changes, and other device data are all stored as events; use this request to search all device data.

See also:
Search Sensor History

Uses and Requirements

Request Components

HTTP Request

POST https://thingspace.verizon.com/api/cc/v1/devices/fields/actions/history/search

Resource Path and Query Parameters

None.

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
Authorization required	string	HTTP Authorization request header containing a valid ThingSpace Bearer token.
VZ-M2M-Token required	string	A valid session token returned by a Connectivity Management API POST /session/login request using the account’s UWS credentials.
Content-Type required	string	Must be `application/json`.

Request Body

The device identifier and fields to match in the search.

Property Name	Data Type	Description
accountidentifier required	JSON object	The ID of the authenticating billing account, in the format `{"billingaccountid":"1234567890-12345"}`.
resourceidentifier required	JSON object	A device ID type and value that identifies the device to search. Can be any unique device identifier, such as ICCID, ID, or IMEI.
$selection optional	JSON object	A comma-separated list of properties and comparator values to match against event data. See Working with Query Filters for more information. If the request does not include `$selection`, the response will include all stored event data.
$limitnumber optional	integer	The maximum number of events to include in the response. If the request matches more than this number of events, the response will contain an `X-Next` value in the header that can be used as the `page` value in the next request to retrieve the next page of events.
$page optional	string	Unique string from the previous response to retrieve either the next page (`X-Next` value) or the previous page (`X-Prev` value) of events.

Example Request Body

Find the two most recent configuration events

curl POST https://thingspace.verizon.com/api/cc/v1/devices/fields/actions/history/search \
  -H 'Authorization: Bearer 021833fbee3e118019f67777e028067f' \
  -H 'VZ-M2M-Token: f1ffff45-ed4c-4db0-a98c-a371afe23b6a' \
  -H 'Content-Type: application/json' \
  -d '{
    "accountidentifier": {"billingaccountid":"1223334444-00001"},
    "resourceidentifier": {"imei":864508030084997},
    "$selection": {"kind":"ts.event.configuration"},
    "$limitnumber": 2
  }'

Success Responses

Status 200

A success response includes an array of all matching events. Each event includes the full event resource definition.

Property Name	Data Type	Description
action	string	The action requested in this event; “change” for device configuration changes.
createdon	string, date-time	The date and time of the change request.
description	string	Description of the event.
deviceid	string, UUID	The device’s ThingSpace UUID.
errmsg	string
fields	JSON object	List of fields affected by the event.
foreignid	string, UUID
id	string, UUID	The unique ID of this ts.event.configuration event.
kind	string	The kind of the ThingSpace resource that is being reported; “ts.event.configuration” for device configuration changes.
lastupdated	string, date-time	The date and time that the event was last updated.
name	string	The name of the event; “SetConfigurationReq” for device configuration changes.
state	string	The current status of the request. The value will be “pending” until the device wakes up and ThingSpace can send the request to the device.
tagids	array, UUIDs	UUIDs of tag resources that are applied to this device.
transactionid	string, UUID
version	string
versionid	string, UUID	The version of the resource.

Example Success Response

[
  {
    "action": "set",
    "createdon": "2019-02-21T02:05:25.270417481Z",
    "description": "[200]-OK",
    "deviceid": "8461f530-2e31-6e87-e357-6c38251d4d01",
    "fields": {
      "configuration": {
        "frequency": "Medium",
        "location_mode": "gps"
      }
    },
    "id": "e521b8ae-440d-6cc1-f687-7c80e085ff29",
    "kind": "ts.event.configuration",
    "lastupdated": "2019-02-21T02:05:25.394230017Z",
    "name": "SetConfigurationReq",
    "state": "update",
    "tagids": [
      "4d110e4f-7a7c-6b26-eaac-31cc34c6e1d4",
      "cd81ed16-18ae-6c7d-eaba-2883b0395387"
    ],
    "transactionid": "c7a0a8cf-6856-4733-93ea-69913650e4ca",
    "version": "1.0",
    "versionid": "270e4820-357d-11e9-9d6c-02420a470c06"
  },
  {
    "action": "set",
    "createdon": "2019-02-21T01:58:45.163Z",
    "deviceid": "8461f530-2e31-6e87-e357-6c38251d4d01",
    "fields": {
      "configuration": {
        "frequency": "Medium",
        "location_mode": "gps"
      }
    },
    "id": "25819e96-c4f2-6545-fb68-0e1d9662359f",
    "kind": "ts.event.configuration",
    "lastupdated": "2019-02-21T01:58:45.163Z",
    "state": "pending",
    "tagids": [
      "4d110e4f-7a7c-6b26-eaac-31cc34c6e1d4",
      "cd81ed16-18ae-6c7d-eaba-2883b0395387"
    ],
    "transactionid": "c7a0a8cf-6856-4733-93ea-69913650e4ca",
    "version": "1.0",
    "versionid": "387fe2fe-357c-11e9-ae40-02420a49140a"
  }
]

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.