Last Values: Retrieve and Search Last Values

Sometimes instead of querying entire events, you just need the last value of some tags. If you just need the last value, the query can be faster since it is looked up from a specific cached last value table instead of from the events stream.

 

Similarly, it can be useful to search the last values to see which users or devices contain a specific value. 

 

Get the last value for specific tags

Available only for portal version 2021.0226 and later. 

This is a common endpoint to get the last value for tags.

 

Summary

  • Endpoint: /device_last_values
  • Method: GET
  • Required User Type: None, this works for all users

URL Parameters

Note: All tags must be written with their stream, ie "raw.device_id", where "raw" is the stream and "device_id" is the tag

  • device_id - API basic user you want to query data from
    • Required
    • Allowed users:
      • Any devices linked to the current tenant
      • Tenant basic user
      • User basic user
      • If super admin/user: can query from any user
  • tag - tag you want to query
    • Required
    • You can set more than one tag

Response

A successful response will return an array of arrays.

Each array represents a different queried tag. These arrays contain objects of the format:

{"timestamp": <ISO string of event containing tag>, <tag>: <value>}

Example

Request URL

https://portal-example.mediumone.com/device_last_values?device_id=device1&tag=device_info.site&tag=device_info.gps

Response Data

[
[
{
"timestamp": "2020-06-17T14:42:59.661378+00:00",
"device_info.gps": "33.8120918 -117.9211629"
}
],
[
{
"timestamp": "2020-04-21T03:05:54.596182+00:00",
"device_info.site": "Medium One"
}
]
]

 

Get the last value for a large tag list

Available only for portal version 2021.0226 and later. 

This is an alternative endpoint to the GET method above.  This uses a POST method which allows for a large list of tags to be requested.

 

Summary

  • Endpoint: /device_last_values/{device_id}
  • Method: POST
  • Required User Type: None, this works for all users

Body Parameters

  • tags (required): list of tags

Response

A successful response will return an array of arrays.

Each array represents a different queried tag. These arrays contain objects of the format:

{"timestamp": <ISO string of event containing tag>, <tag>: <value>}

Example

Request URL

/device_last_values/device01

Request Body

{
tags: ["device_info.gps","device_info.site"]
}

Response Data

[
[
{
"timestamp": "2020-06-17T14:42:59.661378+00:00",
"device_info.gps": "33.8120918 -117.9211629"
}
],
[
{
"timestamp": "2020-04-21T03:05:54.596182+00:00",
"device_info.site": "Medium One"
}
]
]

Get the last n values for specific tags [deprecated]

Note: this query is deprecated and it is recommended you use the above query if you have portal version 2021.0204 or later. The above query is much faster.

 

This is a common endpoint to get the last N values for tags.

N = 1 will have much faster performance than N > 1, so try to use N= 1 when possible. N = 1 looks up the value from a specific cached last values table while any other limit extracts the values from the entire events table.

Summary

  • Endpoint: /last_n_values
  • Method: GET
  • Required User Type: None, this works for all users

URL Parameters

Note: all tags must be written with their stream, ie "raw.device_id", where "raw" is the stream and "device_id" is the tag

  • device_id - user you want to query data from
    • Required
    • Allowed users:
      • Any devices linked to current tenant
      • Tenant basic user
      • User basic user
      • If super admin/user: can query from any user
  • tag - tag you want to query
    • Required
    • Type: list of strings
    • You can set more than one tag
  • limit - number of values to query for each tag (N)
    • Default: 1
    • Cannot be larger than 10

Response

A successful response will return an array of arrays.

Each array represents a different queried tag. These arrays contain objects of the format:

{"timestamp": <ISO string of event containing tag>, <tag>: <value>}

Example

Request Body

{
device_id: 'accounts',
tag: ['licensee_accounts.amount'],
}

Response Data

[
[
{
"timestamp":"2020-01-07T01:06:31.484870+00:00",
"licensee_accounts.amount": 100
}
]
]

 

Search device tags from all accounts

You can use the following endpoint within your custom pages in order to search for specific devices linked to any account.

Note: ALL values are returned as strings, so if you are working with numbers, lists, or objects, you will have to convert them for use.

Summary

  • Endpoint: /last_values_constrained
  • Method: POST
  • Required User Type: Super Admin or Super User

Body Parameters

Note: all tags must be written with their stream, ie "raw.device_id", where "raw" is the stream and "device_id" is the tag

  • devices - list of device IDs to search
    • Default: all devices linked to tenant
    • Type: list of strings
  • search_tags - list of tags to search
    • Default: all tags
    • Type: list of strings
    • Required with use of search_values
  • search_values - list of values to search for in each tag
    • Default: empty string (will match all values)
    • Type: list of strings
    • Required with use of search_tags
  • output_tags - list of tags to return in response
    • Default: all tags
    • Type: list of strings
  • constraint_tag - tag that you want to check has a certain value
    • Default: None
    • Type: string
    • Required with use of constraint_value
  • constraint_value - if a device has the tag constraint_tag and its value is equal to constraint_value, the device will be included in the search, otherwise it will not be included
    • Default: None
    • Type: string
      • Even if you are a non-string tag this value should be a string. For example, for a boolean tag, you would set constraint_value to "true" or "false".
    • Required with use of constraint_tag
  • with_timestamps - if true, "observed_at" timestamp from the event for each last value will be included in the response
    • Default: False
    • Type: boolean

Response

A successful response will return an array of arrays.

The first array defines what each index of the following arrays contain. Each of the arrays represents a different device and contains the following:

  • Index 0: device_id
  • Index 1: list of returned tags for the device
  • Index 2: list of returned values corresponding to the tags in index 1
  • Index 3 (if "with_timestamps" parameter is true): list of "observed_at" timestamps from events containing last value for each tag

Example

Request Body

{
output_tags: ["raw.device_id", "device_data.status"],
search_values: ["bot"],
search_tags: ["raw.device_id"],
with_timestamps: true
}

Response Data

[
[
"bot_1",
["raw.device_id", "device_data.status"],
["bot_1", "active"],
["2020-03-13T23:17:56.490452+00:00","2020-01-10T07:48:11.592129+00:00"]
],
[
"bot_2",
["raw.device_id"],
["bot_2"],
["2020-03-13T23:20:00.000110+00:00","2020-01-10T07:50:12.514231+00:00"]
]
]

 

Search tags from all accounts with pagination

This is the same endpoint as above, but it uses pagination.

Note: ALL values are returned as strings, so if you are working with numbers, lists, or objects, you will have to convert them for use. 

Summary

  • Endpoint: /last_values_constrained_with_pagination
  • Method: POST
  • Required User Type: Super Admin or Super User

Body

Note: all tags must be written with their stream, ie "raw.device_id", where "raw" is the stream and "device_id" is the tag

  • devices - list of device IDs to search
    • Default: all devices linked to tenant
    • Type: list of strings
  • search_tags - list of tags to search
    • Default: all tags
    • Type: list of strings
    • Required with use of search_values
  • search_values - list of values to search for in each tag
    • Default: empty string (will match all values)
    • Type: list of strings
    • Required with use of search_tags
  • output_tags - list of tags to return in response
    • Default: all tags
    • Type: list of strings
  • constraint_tag - tag that you want to check has a certain value
    • Default: None
    • Type: string
    • Required with use of constraint_value
  • constraint_value - if a device has the tag constraint_tag and its value is equal to constraint_value, the device will be included in the search, otherwise it will not be included
    • Default: None
    • Type: string
      • Even if you are a non-string tag this value should be a string. For example, for a boolean tag, you would set constraint_value to "true" or "false".
    • Required with use of constraint_tag
  • limit - number of results to return if using pagination
    • Default: None
    • Type: integer
    • Required with use of start_pagination_id
  • start_pagination_id - pagination will start after this ID
    • Default: None
    • Type: string
    • Required with use of limit
      • When getting first page, set start_pagination_id to "0"

Response

A successful response will return an array of arrays.

The first array defines what each index of the following arrays contain. Each of the arrays represents a different device and contains the following:

  • Index 0: device_id
  • Index 1: list of returned tags for the device
  • Index 2: list of returned values corresponding to the tags in index 1
  • Index 3: pagination ID

Example

Request Body

{
output_tags: ["raw.device_id", "device_data.status"],
search_values: ["bot"],
search_tags: ["raw.device_id"],
start_pagination_id: "0",
limit: 1
}

Response Data

[["bot_1", ["raw.device_id", "device_data.status"], ["bot_1", "active"], "12345"]]

 

Next Response Body

{
output_tags: ["raw.device_id", "device_data.status"],
search_values: ["bot"],
search_tags: ["raw.device_id"],
start_pagination_id: "12345",
limit: 1
}

Next Response Data

[["bot_2", ["raw.device_id"], ["bot_2"], "11122"]]

 

Search tags within an account

You can use the following endpoint within your custom pages in order to search for specific devices linked to a tenant.

Note: ALL values are returned as strings, so if you are working with numbers, lists, or objects, you will have to convert them for use.

Summary

  • Endpoint: /api/v2/tenant/search_devices
  • Method: POST
  • Required User Type: Account Admin

Body

Note: all tags must be written with their stream, ie "raw.device_id", where "raw" is the stream and "device_id" is the tag

  • devices - list of device IDs to search
    • Default: all devices linked to tenant
    • Type: list of strings
  • search_tags - list of tags to search
    • Default: all tags
    • Type: list of strings
    • Required with use of search_values
  • search_values - list of values to search for in each tag
    • Default: empty string (will match all values)
    • Type: list of strings
    • Required with use of search_tags
    • The search looks for values that contain any of the search_values (case insensitive) - it does NOT have to be an exact match
  • output_tags - list of tags to return in response
    • Default: all tags
    • Type: list of strings
  • constraint_tag - tag that you want to check has a certain value
    • Default: None
    • Type: string
    • Required with use of constraint_value
  • constraint_value - if a device has the tag constraint_tag and its value is equal to constraint_value, the device will be included in the search, otherwise it will not be included
    • Default: None
    • Type: string
      • Even if you are constraining with a non-string tag this value should be a string. For example, for a boolean tag, you would set constraint_value to "true" or "false".
    • Required with use of constraint_tag
  • limit - number of results to return if using pagination
    • Default: None
    • Type: integer
    • Required with use of start_pagination_id
  • start_pagination_id - pagination will start after this ID
    • Default: None
    • Type: string
    • Required with use of limit
      • When getting first page, set start_pagination_id to "0"

Response

A successful response will return an array of arrays.

Each of the arrays represents a different device and contains the following:

  • Index 0: device_id
  • Index 1: list of returned tags for the device
  • Index 2: list of returned values corresponding to the tags in index 1
  • Index 3: pagination ID

Example

Request Body

{
output_tags: ["raw.device_id", "device_data.status"],
search_values: ["bot"],
search_tags: ["raw.device_id"]
}

Response Data

[
[
"bot_1",
["raw.device_id", "device_data.status"],
["bot_1", "active"],
"12345"
],
[
"bot_2",
["raw.device_id"],
["bot_2"],
"11122"
]
]

 

Search tags within an account with timestamps

This is the same as the above endpoint, but with timestamps

Note: ALL values are returned as strings, so if you are working with numbers, lists, or objects, you will have to convert them for use.

Summary

  • Endpoint: /api/v2/tenant/search_devices_ts
  • Method: POST
  • Required User Type: Account Admin

Body

Note: all tags must be written with their stream, ie "raw.device_id", where "raw" is the stream and "device_id" is the tag

  • devices - list of device IDs to search
    • Default: all devices linked to tenant
    • Type: list of strings
  • search_tags - list of tags to search
    • Default: all tags
    • Type: list of strings
    • Required with use of search_values
  • search_values - list of values to search for in each tag
    • Default: empty string (will match all values)
    • Type: list of strings
    • Required with use of search_tags
    • The search looks for values that contain any of the search_values (case insensitive) - it does NOT have to be an exact match
  • output_tags - list of tags to return in response
    • Default: all tags
    • Type: list of strings
  • constraint_tag - tag that you want to check has a certain value
    • Default: None
    • Type: string
    • Required with use of constraint_value
  • constraint_value - if a device has the tag constraint_tag and its value is equal to constraint_value, the device will be included in the search, otherwise it will not be included
    • Default: None
    • Type: string
      • Even if you are constraining with a non-string tag this value should be a string. For example, for a boolean tag, you would set constraint_value to "true" or "false".
    • Required with use of constraint_tag
  • limit - number of results to return if using pagination
    • Default: None
    • Type: integer
    • Required with use of start_pagination_id
  • start_pagination_id - pagination will start after this ID
    • Default: None
    • Type: string
    • Required with use of limit
      • When getting first page, set start_pagination_id to "0"

Response

A successful response will return an array of arrays.

Each of the arrays represents a different device and contains the following:

  • Index 0: device_id
  • Index 1: list of returned tags for the device
  • Index 2: list of returned values corresponding to the tags in index 1
  • Index 3: list of returned timestamps corresponding to the values in index 2
  • Index 4: pagination ID

Example

Request Body

{
output_tags: ["raw.device_id", "device_data.status"],
search_values: ["bot"],
search_tags: ["raw.device_id"]
}

Response Data

[
[
"bot_1",
["raw.device_id", "device_data.status"],
["bot_1", "active"],
["2020-03-13T23:20:00.000110+00:00", "2020-03-13T23:20:00.000110+00:00"],
"12345"
],
[
"bot_2",
["raw.device_id"],
["bot_2"],
["2020-03-15T00:20:00.000110+00:00"],
"11122"
]
]