Telemetry

Introduction

Access Token

Access tokens are the secret passwords that gives access to your resources through the APIs. You can create an API token from the Cloud as described in the introduction.
Make sure to keep your tokens secret and to not publish them publicly to prevent any security breach.

API in use

The Cloud API centralizes all your teams, workspaces, devices, applications, logs and telemetries. hub.stereolabs.com/api/v1

List and query telemetries

Get the telemetry from the workspace identified by workspaceId. Multiple parameters are available to customize the output of this endpoint.

:workspaceId integer

Id of the target workspace.

fields string_list

optional Telemetry's fields that should be returned by the request. This can be used to reduce amount of data retrieved by only selecting the needed fields. ?fields=timestamp,label,payload

Available fields: id, device_id, timestamp, payload, retention, label, tags.
Payload fields: A field can also be taken from the payload with the following notation. ?fields=payload.temperature,payload.humidity

ids integer_list

optional Filter the telemetries from their Id. ?ids=125,356,542

devices integer_list

optional Filter telemetries based on the devices that emitted them. ?devices=1,5

labels string_list

optional Filter telemetries based on their label. ?labels=detections,environment

tags string_list

optional Only select telemetries matching all the tags listed. ?tags=main_building

start
end timestamp

optional Only target the telemetry published within the specified the time-range. ?start=1567413071229&end=1567419371229
start and end can be used independently. Timestamps can be provided in the following formats:

start=1567419371229 A milliseconds UTC EPOCH UNIX timestamp.
start=2019-09-02T11:21:11,229+02:00 An ISO8601 datetime string (must be url-encoded).

sort
sort_direction field_list
string_list

optional Sort the returned telemetry by the specified key. ?sort=timestamp&sort_direction=DESC
The order can be specified with the sort_direction parameter that can be DESC or ASC whether you are using descending or ascending sorting. If more than one key is given, the next fields will be used when sorting with the previous key reported an equality. ?sort=label,payload.humidity&sort_direction=ASC,DESC

filter_op
filter_field
filter_value string
field
value

optional Filter out telemetry that doesn't match the specified condition. ?filter_field=payload.temperature&filter_op=gt&filter_value=30
Only return telemetry with a reported temperature over 30° (where temperature is a custom field in the payload).
Available filter operations are:

gt: is greater than
gte: is greater than or equal
lt: is lower than
lte: is lower than of equal
eq: is equal
neq: is different
contains: is containing the value (string)

To avoid type ambiguity when filtering on a payload key, use the filter_value_type parameter and set it to number or string.
To use more than one filter, append from _1 to _10 at the end of each filter_* parameter. ?filter_field_2=payload.humidity&filter_op_2=eq&filter_value_2=95

agg
agg_field
agg_step string
field
timestamp

optional This parameter will change the output format by returning aggregates of telemetry in time-intervals rather than a telemetry list.
?agg=mean&agg_field=payload.temperature&start=1567413071229&end=1567419371229
Returns the average temperature in a time-range (where payload.temperature is a custom field).
Available aggregations are:

count: Count the number of telemetry matching the provided parameters
sum: Sum of the values found in the queried telemetry for the agg_field
avg: Average of the values found in the queried telemetry for the agg_field
min: Minimum value found in the queried telemetry for the agg_field
max: Maximum value found in the queried telemetry for the agg_field

If an agg_step is provided, result will be split in multiple time ranges, starting from start and incrementing by agg_step up to the end.
An additional agg_identifier can be used to split result in groups based on key's value.
?agg=count&agg_identifier=device_id&start=1567413071229&end=1567419371229&agg_step=36000000
Count the number of telemetry reported by each device in 10 minutes intervals.

per_page
page
after integer
integer_or_field
value

optional Controls the pagination of the returned telemetry list. ?per_page=25
By default, the telemetry's timestamp is used to sort the returned page, providing the latest telemetry first.

Keyset pagination By using page to select the sorting key, and after to specify the position of the page, pagination will return per_page telemetries starting right after after value ?per_page=25&page=timestamp&after=1567413071229.
Offset pagination By using page as a number, pagination will return per_page telemetries starting from the most recent one. ?per_page=25&page=1

limit
offset integer
integer

optional Skip some telemetry (offset) and limits the number of telemetry returned by the request. ?offset=50&limit=25

telemetry array

List of telemetry matching the specified parameters.

/workspaces/:workspaceId/telemetry

curl -s \
  -H "Content-Type:application/json" \
  -H "Authorization:Bearer ${access_token}" \
 https://hub.stereolabs.com/api/v1/workspaces/:workspaceId/telemetry \
  -G  \
  -d 'labels=robot' \
  -d 'fields=timestamp,payload.temperature' \
  -d 'start=1580201472695' \
  -d 'filter_field=payload.temperature' \
  -d 'filter_op=gt' \
  -d 'filter_value=30'

HTTP/1.1 200 OK
{
  "telemetry": [
     {
       "timestamp": "1580205472695",
       "payload": {
         "temperature":31
       }
   },
   {   "timestamp": "1580209472695",
       "payload": {
         "temperature":45
       }
   },
   ...
 ]
}

Publish telemetry

Publish a new telemetry from the specified device.

:workspaceId integer

Id of the target workspace.

:deviceNameOrId integer

Id or url-encoded name of the associated device.

label string

A string representing the type of telemetry sent. This field is later used during data consultation to filter relevant telemetry.

tags string_list

optional A comma-separated list of tag to associate with the telemetry. Tags could be used in queries to filter specific telemetries.

payload object

The actual telemetry data in a json format. This is where you can add custom fields representing your telemetry.

timestamp timestamp

optional The time at which the telemetry has been generated. Default value is the timestamp at which the request is sent.
Timestamp can be provided in the following formats:

start=1567419371229 A milliseconds UTC EPOCH UNIX timestamp.
start=2019-09-02T11:21:11,229+02:00 An ISO8601 datetime string. (must be url-encoded)

retention number

optional The retention time of this telemetry in days. If not set, the default value of 1 month (30 days) will be used.

id integer

ID of the created telemetry.

/workspaces/:workspaceId/devices/:deviceNameOrId/telemetry

curl -s \
  -H "Content-Type:application/json" \
  -H "Authorization:Bearer ${access_token}" \
  -X POST \
 https://hub.stereolabs.com/api/v1/workspaces/:workspaceId/devices/:deviceNameOrId/telemetry \
  -d '{ 
  "timestamp": 1567416071229, 
  "label": "people detection", 
  "payload": { 
    "people_count": 54,
    "accuracy_percent": 98
  }
}'

HTTP/1.1 200 OK
{
  "id": "313233"
}

Delete telemetry

Delete telemetries matching the parameters.

:workspaceId integer

Id of the target workspace.

ids integer_list

optional Filter the telemetries from their Id. ?ids=125,356,542

devices integer_list

optional Filter telemetries based on the devices that emitted them. ?devices=1,5

labels string_list

optional Filter telemetries based on their label. ?labels=detections,environment

start
end timestamp

start=1567419371229 A milliseconds UTC EPOCH UNIX timestamp.
start=2019-09-02T11:21:11,229+02:00 An ISO8601 datetime string. (must be url-encoded)

/workspaces/:workspaceId/telemetry

curl -s \
  -H "Content-Type:application/json" \
  -H "Authorization:Bearer ${access_token}" \
  -X DELETE \
 https://hub.stereolabs.com/api/v1/workspaces/:workspaceId/telemetry \
  -G  \
  -d 'devices=67890' \
  -d 'labels=detections' \
  -d 'start=1580201472695' \
  -d 'end=1580312563849'

HTTP/1.1 200 OK
{}