Read Raw Historical Data at Time

  • Retrieves raw historical values for the specified timestamp of one or more items.

  • Required security permission - READ.

  • HTTP methods supported: GET.

Description

This endpoint allows to read raw value and quality at the specified time if it exists, otherwise the leading bounding value will returned in the past of one or more items.

By default this endpoint returns the timestamp (t) as milliseconds since epoch. The format can be changed to an ISO 8601 date string with Zulu format, by providing the 'time_zone' option with the value 'UTC±00:00' or 'UTC'.

Parameters

Name Type Optional Description

timestamp

string

no

The timestamp (UTC) to retrieve data for.

identifier

string

no

Item or property path.

bounds

undefined

yes

A Boolean or number. Indicates which data point should be returned in case no data point exists at the provided timestamp, default value is 2 = leading.

Value Description

0 / false

None

1 / true

leading or trailing (if exists)

2

leading (if exists)

3

trailing (if exists)

time_zone

string

yes

Can be used to define the time zone and format of the timestamp in the response. Currently only the values 'epoch' and 'UTC' or 'UTC±00:00' are supported to define whether the format of the timestamp should be the ISO 8601 Zulu format or the UTC Epoch format.

fields

string

yes

Comma separated string to customize which fields should be included in the response, by default 'i,p,v,q,t'. Provide 'ALL' to include all fields.

insights

boolean

yes

Indicates application insights should be included in the response, by default false.

Bounds

The following overview shows which data point will be returned based on the provided timestamp and bounds option.

Timestamp / Bounds 0 / false 1 / true 2 = leading 3 = trailing

Before historical time frame

none (BadNoData)

trailing

none (BadBoundNotFound)

trailing

Matching data point timestamp

data point at timestamp

data point at timestamp

data point at timestamp

data point at timestamp

Between two data points

none (BadNoData)

leading

leading

trailing

After historical time frame

none (BadNoData)

leading

leading

none (BadBoundNotFound)

Examples

Read raw value at time

A simple example of reading raw historical data of single or multiple items are provided below. Extra parameters can be added to the URL by adding a & sign, for example /api/v2/readrawhistoricaldataattime?timestamp=2019-03-20T08:06:33.599Z&identifier=/System/Core/Examples/Demo Data/Process Data/DC666&fields=ALL.

HTTP GET

Request URL

  • Single /api/v2/readrawhistoricaldataattime?timestamp=2021-03-20T08:06:33.599Z&identifier=/System/Core/Examples/Demo Data/Process Data/DC666

  • Multiple api/v2/readrawhistoricaldataattime?timestamp=2021-03-20T08:06:33.599Z&identifier=/System/Core/Examples/Demo Data/Process Data/DC666&identifier=/System/Core/Examples/Demo Data/Process Data/DC4711

Response Body

  • Single

{
    "data": [
        {
            "i": 281474986213376,
            "p": "/System/Core/Examples/Demo Data/Process Data/DC666",
            "q": 0,
            "t": 1616227578931,
            "v": 12.000750732421887
        }
    ]
}

  • Multiple

{
    "data": [
        {
            "i": 281474986213376,
            "p": "/System/Core/Examples/Demo Data/Process Data/DC666",
            "q": 0,
            "t": 1616227578931,
            "v": 12.000750732421887
        },
        {
            "i": 281474986016768,
            "p": "/System/Core/Examples/Demo Data/Process Data/DC4711",
            "q": 0,
            "t": 1616227578931,
            "v": 8.996197509765598
        }
    ]
}

Read example no data point

This example shows a read raw historical data at time request, where the timestamp is before historical time frame and default (2 = leading (if exists)) bounds setting. The HTTP status code of the response is in this example 200 (OK). The response value depends on the timestamp and the bounds setting, see Bounds section.

HTTP GET

Request URL

  • /api/v2/readrawhistoricaldataattime?timestamp=2019-03-20T08:06:33.599Z&identifier=/System/Core/Examples/Demo Data/Process Data/DC666&fields=ALL

Response Body

{
    "data": [
        {
            "i": 281474986016768,
            "p": "/System/Core/Examples/Demo Data/Process Data/DC4711",
            "q": 2157641728,
            "t": "2019-03-20T08:06:33.599Z",
            "v": null
        }
    ]
}

Read historical data at time failure response

This example shows a read historical data at time response of a failed read request due to incorrect object path. The HTTP status code of the response is in this example 200 (OK). Response contains an error message and object path.

HTTP GET

Request URL

  • /api/v2/readrawhistoricaldataattime?timestamp=2019-03-20T08:06:33.599Z&identifier=/System/Core/Examples/Demo Data/Process Data/DC000

Response Body

{
    "data": [
        {
            "error": {
                "msg": "Permission denied. 'Object '/System/Core/Examples/Demo Data/Process Data/DC000' could not be resolved."
            },
            "p": "/System/Core/Examples/Demo Data/Process Data/DC000"
        }
    ]
}