Read Historical Data at Time

  • Retrieves 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 value and quality at the specified time in the past of one or more items.

Parameters

Name Type Optional Description

timestamp

string

no

The timestamp (UTC) to retrieve data for.

identifier

string

no

Item or property path.

sloped_extrapolation

boolean

yes

Indicates how the server interpolates data when no boundary value exists (i.e. extrapolating into the future from the last known value); optional parameter, by default false.

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.

Examples

Read value at time

A simple example of reading 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/readhistoricaldataattime?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/readhistoricaldataattime?timestamp=2019-03-20T08:06:33.599Z&identifier=/System/Core/Examples/Demo Data/Process Data/DC666

  • Multiple api/v2/readhistoricaldataattime?timestamp=2019-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": "2019-03-20T08:06:33.599Z",
            "v": 2.425097656250002
        }
    ]
}

  • Multiple

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

Read example no data point

This example shows a read historical data at time request, where in the timestamp specified object contains no data. The HTTP status code of the response is in this example 200 (OK). The response value and the quality indicate that there is no data for this object at the requested timestamp.

HTTP GET

Request URL

  • /api/v2/readhistoricaldataattime?timestamp=2018-04-20T08%3A06%3A33.599Z&identifier=%2FSystem%2FCore%2FExamples%2FDemo%20Data%2FProcess%20Data%2FDC666&fields=ALL

Response Body

{
    "data": [
        {
            "i": 281474986213376,
            "p": "/System/Core/Examples/Demo Data/Process Data/DC666",
            "q": 2157641728,
            "qs": 2,
            "qstxt": "Bad",
            "qtxt": "BadNoData",
            "t": "2018-04-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/readhistoricaldataattime?timestamp=2018-04-20T08%3A06%3A33.599Z&identifier=%2FSystem%2FCore%2FExamples%2FDemo%20Data%2FProcess%20Data%2FDC000

Response Body

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