Reading device state through State object

You can read full device state including its meta data, methods, properties and alerts. You can also shape the response object by providing parameters shown below.

If you are writing using a device key you can substitute {ref} with _this_.

Api Key Authorization

Required FieldsValues
Context typeDevice or App

State Object

Device state is a compact representation of device metadata, and the most recent device values. It is mainly consists of 4 sections:

  1. State Header: mainly device metadata plus some additional fields
  2. List of property instances: property metadata and the most recent instant value
  3. List of method instances: method metadata and method statistics
  4. List of alert instances: alert metadata and alert statistics

Most recent property values, method and alert statistics only show up after the first use. Users can customize state view using query parameters (see below) to include or exclude sections.

State header

Below we list attributes specific to device state header.

initiatedAtDevice backend start date and time in ISO 8601 format. This is mostly used for debugging purposes. In general, a device backend begins to exist with the first incoming or outgoing data, but cluster manager can kill or start device backends as it sees fit.
ingestionDevice ingestion rate. It consists of 2 fields: rateLimit defines the maximum number of feeds per minute, and maxNrOfDpPerFeed defines the maximum number of data points allowed per feed. ingestion cannot be changed by the user; it is automatically set by device's account plan. See your account plan details for device ingestion rates.


It consists of 4 subsections: ref, meta, value and stats. ref shows the property references, meta show the details of the property, value is the most recent value written into the property and stats shows the write statistics of this property.

At minimum, it has only ref and meta subsection. value and stats subsections show up only after the first write operation.

meta subsection contains the property instance meta data, value subsection contains the most recent value of the property instance in form of data value object, stats subsection contains property statistics where count shows how many times this property is set since its owner object is created.

Below we show a fully populated value and stats subsections of a numeric property instance. Non numeric properties contain only count field in their stats subsections.

"ref": {
  "id": "_prp_944478333222595585",
  "qname": "mysensor$temp"
"meta": {
  "id": "_prp_944478333222595585",
  "accountId": "_acc_944477132420380208",
  "ownerId": "_dpf_944477240279924130",
  "name": "Temp",
  "friendlyName": "Temperature",
  "qualifiedName": "mysensor$temp",
  "description": "Indoor temperature readings",
  "type": "number",
  "access": "protected",
  "publish": "changed",
  "retention": {
    "type": "mostrecent",
      "condition": {
        "when": "always"
  "locked": false,
  "dateCreated": "2017-06-27T03:07:42.324Z",
  "dateModified": "2017-06-27T03:07:42.324Z"
"value": {
  "mostRecent": 23,
  "time": "2017-07-21T00:27:59.123Z",
  "annotations": {
    "customer-id": "8CS238429929348923"
  "location": {
    "zone": "Portland Factory",
    "geo": {
      "lat": 41.0296287,
      "lon": 28.6232202,
      "alt": 0
  "tags": [
"stats": {
  "count": 3,
  "min": 23,
  "max": 23,
  "sum": 69 


Method consists of 5 sections. ref, meta, lastExecution, stats and disabled. lastExecution shows a brief about the last execution. time shows execution time in milliseconds. stats section shows how many times this method is executed, minimum and maximum execution times in milliseconds.

"ref": {
  "id": "_mtd_944552945643610010",
  "qname": "mysensor$gettemperature"
"meta": {
  "id": "_mtd_944552945643610010",
  "accountId": "_acc_944477132420380208",
  "ownerId": "_dpf_944478335659071432",
  "name": "getTemperature",
  "friendlyName": "getTemperature",
  "inherited": false,
  "qualifiedName": "mysendor$gettemperature",
  "access": "public",
  "inputTTL": "5 seconds",
  "inputId": "_prp_944478333222595585",
  "methodImpl": {
    "funcBody": "if (value > 35.0) { return \"hot\" } else { return \"warm\"; }",
    "script": "javascript"
  "locked": false,
  "dateCreated": "2017-07-27T05:38:05.593Z",
  "dateModified": "2017-07-27T05:41:48.56Z"
"lastExecution": {
  "status": "Success",
  "at": "2017-07-27T05:49:33.603Z",
  "time": 1
"stats": {
  "count": 1,
  "min": 1,
  "max": 1,
  "sum": 1,
  "failures": 0
"disabled": false
Click Try It! to start a request and see the response here!