Timestream

Description

The timestream module offers the option to store historical data and events. These can than be queried later for analytic purposes.

WARNING

Please use the not deprecated endpoints to start a query. These POST endpoints have been optimized and run faster and produce less traffic. Next to the properties they can return events and offer a much more rich filtering of data. Note: Due to the fact that events might be present, the hierarchy within the response has changed. The response now returns data ordered by device then by service. The old GET endpoints returned data ordered by service then by device.

API

Endpoints

POST

Start Timestream Query

POST

Get Next Batch of Timestream Data

GET

Get Filter Information

GET

Get Write Statistics

GET

Start Timestream Query

GET

Get Next Batch of Timestream Data

POST

Start Timestream Query

POST

Get Next Batch of Timestream Data

Start Timestream Query

Returns the historic data based on a given filter, possibly split into parts.

POST

/api/v1/timestream/iterator

Access

This endpoint requires read permission for the resource timestream.

Request Body

Name	Description
queryData booleanoptional	Whenever or not to query data. Default: true
queryEvents booleanoptional	Whenever or not to query events. Default: true
serviceIdentifier arrayoptional	Array containing the service identifier you want to filter for. If you do not want to filter any services, leave this parameter out of the request.
deviceIdentifier arrayoptional	Array containing the device identifier you want to filter for. If you do not want to filter any devices, leave this parameter out of the request.
propertyIdentifier arrayoptional	Array containing the property identifier you want to filter for. If you do not want to filter any devices, leave this parameter out of the request.
events arrayoptional	Array containing the events you want to filter for.If you do not want to filter any events, leave this parameter out of the request.
from integeroptional	The UTC timestamp in milliseconds from where the returned timeseries should start. Defaults to an hour before the parameter `to`.
to integeroptional	The UTC timestamp in milliseconds to where the returned timeseries should go. Defaults to `right now`.
limit integeroptional	The number of values to return. Can be set to zero in order to return everything. Be careful when using this in combination with a long interval for the time as it will result in a long running query. Default: 100
prependFirstValue booleanoptional	Whenever or not to append a value right before the requested interval of time. This is useful if you want to display the information in a graph and have one value before the actual range to show the correct `baseline` for the step function. However, setting this to `true` does increase the time the query needs to process.

Response

Name	Description
done boolean	Whenever there is data that still can be fetched.
nextToken stringoptional	The token that is used to get the next batch of data. Only present when done is equal to false.
data dictionaryoptional	Object that contains all history data based on the filtering choosen.
events dictionaryoptional	Object that contains all history events grouped under devices
estimatedQueryProgress number	The estimated progress of the query. When the progress reaches 100 percent the query is finished and all data can be fetched rather quickly. While the query is not finished requests to the /next endpoint might return no data at all. This is better described as: `When the progress reaches 100, all important rows in the database have been checked. Now we still need to send them to the client.`

Get Next Batch of Timestream Data

Returns more timestream data based on a token. Should be used in conjunction with the iterativ route.

POST

/api/v1/timestream/next/:nextToken

Access

This endpoint requires read permission for the resource timestream.

URL Parameter

Name	Description
nextToken string	The token from the iterator request.

Response

Name	Description
done boolean	Whenever there is data that still can be fetched.
nextToken stringoptional	The token that is used to get the next batch of data. Only present when done is equal to false.
data dictionaryoptional	Object that contains all history data based on the filtering choosen.
events dictionaryoptional	Object that contains all history events grouped under devices
estimatedQueryProgress number	The estimated progress of the query. When the progress reaches 100 percent the query is finished and all data can be fetched rather quickly. While the query is not finished requests to the /next endpoint might return no data at all. This is better described as: `When the progress reaches 100, all important rows in the database have been checked. Now we still need to send them to the client.`

Get Filter Information

Returns the current filter settings if any.

GET

/api/v1/timestream/filter

Access

This endpoint requires read permission for the resource timestream.

Response

Name	Description

Get Write Statistics

Returns statistics about Timestream write operations for billing purposes. Includes current records per minute, records per second, and max records per minute for the last hour, day, and week.

GET

/api/v1/timestream/stats

Access

This endpoint requires read permission for the resource timestream.

Response

Name	Description
recordsThisMinute integer
minuteStartedAt integer
recordsPerSecond number
maxPerMinuteLastHour integer
maxPerMinuteLastDay integer
maxPerMinuteLastWeek integer

Start Timestream Query

Returns the historic data in batches. The client needs to request following batches via the /next endpoint.

WARNING

Please use the non-deprecated endpoints. There are in many ways and forms superior.

GET

/api/v1/timestream/iterator

Access

This endpoint requires read permission for the resource timestream.

Query Parameter

Name	Description
from integeroptional	The UTC timestamp in milliseconds from where the returned timeseries should start. If possible, the response will contain one value before the given timestamp. Defaults to an hour before the query parameter `to`.
to integeroptional	The UTC timestamp in milliseconds to where the returned timeseries should go. If possible, the response will contain one value after the given timestamp. Defaults to `right now`.
limit integeroptional	The number of values to return. Can be set to zero in order to return everything. Be careful when using this in combination with a long interval for the time as it will result in a long running query. Default: 100

Response

Name	Description
done boolean	Whenever there is data that still can be fetched.
token stringoptional	The token that is used to get the next batch of data. Only present when done is equal to false.
data dictionaryoptional	Object that contains all history data. Only present when done is equal to false.

Get Next Batch of Timestream Data

Returns the next batch for the timestream data.

WARNING

Please use the non-deprecated endpoints. There are in many ways and forms superior.

GET

/api/v1/timestream/next/:nextToken

Access

This endpoint requires read permission for the resource timestream.

URL Parameter

Name	Description
nextToken string	The token from the iterator request.

Response

Name	Description
done boolean	Whenever there is data that still can be fetched.
token stringoptional	The token that is used to get the next batch of data. Only present when done is equal to false.
data dictionaryoptional	Object that contains all history data. Only present when done is equal to false.

Start Timestream Query

Returns the historic data in batches. The client needs to request following batches via the /next endpoint.

WARNING

Please use the non-deprecated endpoints. There are in many ways and forms superior.

POST

/api/v2/timestream/iterator

Access

This endpoint requires read permission for the resource timestream.

Request Body

Name	Description
queryData booleanoptional	Whenever or not to query data. Default: true
queryEvents booleanoptional	Whenever or not to query events. Default: true
serviceIdentifier arrayoptional	Array containing the service identifier you want to filter for. If you do not want to filter any services, leave this parameter out of the request.
deviceIdentifier arrayoptional	Array containing the device identifier you want to filter for. If you do not want to filter any devices, leave this parameter out of the request.
propertyIdentifier arrayoptional	Array containing the property identifier you want to filter for. If you do not want to filter any devices, leave this parameter out of the request.
events arrayoptional	Array containing the events you want to filter for.If you do not want to filter any events, leave this parameter out of the request.
from integeroptional	The UTC timestamp in milliseconds from where the returned timeseries should start. Defaults to an hour before the parameter `to`.
to integeroptional	The UTC timestamp in milliseconds to where the returned timeseries should go. Defaults to `right now`.
limit integeroptional	The number of values to return. Can be set to zero in order to return everything. Be careful when using this in combination with a long interval for the time as it will result in a long running query. Default: 100
prependFirstValue booleanoptional	Whenever or not to append a value right before the requested interval of time. This is useful if you want to display the information in a graph and have one value before the actual range to show the correct `baseline` for the step function. However, setting this to `true` does increase the time the query needs to process.

Response

Name	Description
done boolean	Whenever there is data that still can be fetched.
nextToken stringoptional	The token that is used to get the next batch of data. Only present when done is equal to false.
data dictionaryoptional	Object that contains all history data based on the filtering choosen.
events dictionaryoptional	Object that contains all history events grouped under devices
estimatedQueryProgress number	The estimated progress of the query. When the progress reaches 100 percent the query is finished and all data can be fetched rather quickly. While the query is not finished requests to the /next endpoint might return no data at all. This is better described as: `When the progress reaches 100, all important rows in the database have been checked. Now we still need to send them to the client.`

Get Next Batch of Timestream Data

Returns the next batch for the timestream data.

WARNING

Please use the non-deprecated endpoints. There are in many ways and forms superior.

POST

/api/v2/timestream/next/:nextToken

Access

This endpoint requires read permission for the resource timestream.

URL Parameter

Name	Description
nextToken string	The token from the iterator request.

Response

Name	Description
done boolean	Whenever there is data that still can be fetched.
nextToken stringoptional	The token that is used to get the next batch of data. Only present when done is equal to false.
data dictionaryoptional	Object that contains all history data based on the filtering choosen.
events dictionaryoptional	Object that contains all history events grouped under devices
estimatedQueryProgress number	The estimated progress of the query. When the progress reaches 100 percent the query is finished and all data can be fetched rather quickly. While the query is not finished requests to the /next endpoint might return no data at all. This is better described as: `When the progress reaches 100, all important rows in the database have been checked. Now we still need to send them to the client.`