API Read Raw Historical Data At Time

Read the raw historical value (with quality and timestamp) of one or many items as it was at a single specific point in time, optionally returning the leading and/or trailing bounding sample.

Purpose

Exposes the functionality as the Web API ReadRawHistoricalDataAtTime endpoint. For a single timestamp, each item returns one raw sample — the value stored at that time, or the configured bounding sample when no sample falls exactly on the timestamp. Internally each item is read with syslib.getrawhistory(obj, true, timestamp, timestamp + 1, …​) over the resolved data store, and the leading/trailing bound is selected per the bounds option. READ permission is checked per item. When no data is found, a Bad No Data value (quality 0x809B0000) is returned at the requested timestamp.

Invocation Modes

HTTP Endpoints

Standard endpoint:

POST {{baseurl}}/api/v2/readrawhistoricaldataattime
Content-Type: application/json
Authorization: Bearer {{token}}

Advanced endpoint:

POST {{baseurl}}/api/v2/execfunction/syslib.api-readrawhistoricaldataattime/readrawhistoricaldataattime
Content-Type: application/json
Authorization: Bearer {{token}}

Direct Lua

Via API index script:

local api = require('syslib.api')
local result, quality = api:readrawhistoricaldataattime(arg, req, hlp)

Direct script library call:

local rrhdatApi = require('syslib.api-readrawhistoricaldataattime')
local result = rrhdatApi:readrawhistoricaldataattime(arg, req, hlp)

Example

Read one item at a single point in time, default fields (i,p,v,q,t), default bounds (2 — leading bound only):

{
    "timestamp": "2025-03-25T00:00:25.000Z",
    "items": [
        { "p": "/IO-Home/Examples/Demo Data/Process Data/DC0815" }
    ]
}

Response (array of item-value objects, one per request item, in request order):

{
    "data": [
        { "i": "8a1f...", "p": "/IO-Home/Examples/Demo Data/Process Data/DC0815", "v": 12.1, "q": 0, "t": 1742860800000 }
    ]
}

The returned t is the timestamp of the actual sample used (here the leading bound at 00:00:20), not necessarily the requested timestamp.

Example Bank

Read by object ID (GUID)

{
    "timestamp": 1742860825000,
    "items": [
        { "i": "8a1f3c0e-2b4d-4e6f-9a1b-0c2d4e6f8a1b" },
        { "i": 1048576 }
    ]
}
{
    "data": [
        { "i": "8a1f3c0e-2b4d-4e6f-9a1b-0c2d4e6f8a1b", "p": "/IO-Home/Tags/Flow", "v": 3.4, "q": 0, "t": 1742860820000 },
        { "i": 1048576, "p": "/IO-Home/Tags/Level", "v": 7.8, "q": 0, "t": 1742860824000 }
    ]
}

Both bounding samples (bounds: 1)

bounds selects which bound is returned when no sample sits exactly on the timestamp: 0/false = none, 1/true = both start and end, 2 = leading (start) only (default), 3 = trailing (end) only. Because each item returns a single value, 1/true resolves to the leading bound if one exists, otherwise the trailing bound.

{
    "timestamp": "2025-03-25T00:00:25.000Z",
    "opt": { "bounds": 1 },
    "items": [
        { "p": "/IO-Home/Examples/Demo Data/Process Data/DC0815" }
    ]
}
{
    "data": [
        { "i": "8a1f...", "p": "/IO-Home/Examples/Demo Data/Process Data/DC0815", "v": 12.1, "q": 0, "t": 1742860820000 }
    ]
}

Trailing bound only (bounds: 3)

{
    "timestamp": "2025-03-25T00:00:25.000Z",
    "opt": { "bounds": 3 },
    "items": [
        { "p": "/IO-Home/Examples/Demo Data/Process Data/DC0815" }
    ]
}
{
    "data": [
        { "i": "8a1f...", "p": "/IO-Home/Examples/Demo Data/Process Data/DC0815", "v": 12.4, "q": 0, "t": 1742860830000 }
    ]
}

Select specific fields

fields is a comma-separated string (or array). Here only p, v, and t are returned:

{
    "timestamp": "2025-03-25T00:00:25.000Z",
    "fields": "p,v,t",
    "items": [
        { "p": "/IO-Home/Examples/Demo Data/Process Data/DC0815" }
    ]
}
{
    "data": [
        { "p": "/IO-Home/Examples/Demo Data/Process Data/DC0815", "v": 12.1, "t": 1742860820000 }
    ]
}

No data at the requested time

When no sample (and no eligible bound) is found, a Bad No Data value is returned at the requested timestamp:

{
    "data": [
        { "i": "8a1f...", "p": "/IO-Home/Tags/Empty", "v": null, "q": 2157838336, "t": 1742860825000 }
    ]
}

Direct Lua

local api = require('syslib.api')
local result = api:readrawhistoricaldataattime({
    timestamp = "2025-03-25T00:00:25.000Z",
    opt = { bounds = 1 },
    items = {
        { p = "/IO-Home/Examples/Demo Data/Process Data/DC0815" }
    }
}, req, hlp)
-- result[1] = { i = ..., p = "/IO-Home/...", v = 12.1, q = 0, t = 1742860820000 }

Request Contract

Top-level argument (SysLib.API-ReadRawHistoricalDataAtTime.Arg). Options may be supplied at the top level or under opt.

Field Type Required Default Behavior

timestamp

integer or string

yes

—

The single point in time to read at. Epoch milliseconds, or an ISO 8601 string (converted via syslib.gettime; resolved value must be ≥ 0). Missing/invalid → request error (HTTP 412).

items

array

yes

—

Array of query items. Must be a non-empty array, else request error (HTTP 412).

opt

object

no

—

Options (see below). The same option keys are also accepted at the top level.

Per-item object (SysLib.API-ReadRawHistoricalDataAtTime.Arg-Item):

Field Type Required Default Behavior

p

string

conditional

—

Object path. One of p or i is required.

i

string

conditional

—

Object ID (GUID string) or property ID (a <guid>-P-… string). Validated as a GUID string.

Options (opt, type SysLib.API-ReadRawHistoricalDataAtTime.Arg-Options):

Field Type Required Default Behavior

bounds

boolean or integer

no

2

Bounding-sample selection: 0/false = none, 1/true = both start and end, 2 = leading (start) only, 3 = trailing (end) only. A numeric value supplied alongside a false boolean form is honored as the numeric bound.

fields

string or string[]

no

"i,p,v,q,t"

Fields to include per response item. Comma-separated string or array.

data_store

string

no

resolved per item

Data store to read from. When omitted, the item’s default store is resolved via syslib.getdefaultstore.

modified_data_mode

boolean

no

—

Read the modified-data series instead of the raw series.

time_zone

string

no

"epoch"

epoch → numeric ms timestamps; UTC or UTC±00:00 → ISO 9801 timestamps.

Selectable fields

Field Meaning

i

Object ID or Property ID.

p

Object path.

v

Value of the selected sample.

q

Quality code (numeric).

t

Timestamp of the selected sample (epoch milliseconds, integer).

qtxt, qs, qstxt

Full/simple quality text and simple quality code (when requested).

error

Present only on items that failed.

Response Contract

Returns a single object with a data key, that contains an array of item-value results (SysLib.API-ReadRawHistoricalDataAtTime.Result = SysLib.API-ItemValueHelper.Create-Result[]), one per request item, in request order. Each entry carries the fields selected by fields (default i,p,v,q,t):

Field Type Present when

i

string

requested and resolvable

p

string

requested and resolvable

v

unknown

a sample was selected (JSON-encodable; null for Bad No Data)

q

number

quality of the selected sample

t

integer

timestamp of the selected sample

qtxt, qs, qstxt

string/number

requested

error

object

the item failed (see Error Handling)

Each item yields at most one value. When no sample and no eligible bound exist, the item is still returned with v = null, q = 0x809B0000 (Bad No Data, decimal 2157838336) and t = timestamp. The function also returns a response-quality value as its second Lua return.

Permissions

  • Each item requires READ permission on the target object; the check is performed per item via hlp:checkpermission(…​, READ, true). On denial, that item is returned with an error and no value.

  • Runs in the context of the authenticated user.

Error Handling

Request-level (whole call) errors return an error VQT with HTTP status 412:

Condition Message

timestamp missing or not a number/string

Argument 'timestamp' is missing or not a number or a string.

timestamp string cannot be parsed

Value '<timestamp>' of 'timestamp' argument is invalid.

items missing or not a non-empty array

Missing or invalid 'items' argument. Should be an array.

arg not a table

assertion: Invalid argument 'arg'. Should be a Lua table.

Per-item errors are captured on that item (others still return); the entry carries an error field instead of a value. Common messages:

Condition Message

Neither p nor i provided

Missing path or identifier.

READ permission denied

permission error from checkpermission

getrawhistory runtime failure

underlying error string (caught via pcall)

Notes

  • The timestamp argument is a single time, not an array; each request reads all items at that one point in time. To read at several times, issue multiple requests.

  • A sample whose quality is Bad Bound Not Found (0x80D70000) at the exact timestamp is only used when a bound is requested; otherwise it is skipped. For a trailing bound carrying that quality, the returned t is reset to the requested timestamp rather than the internal timestamp + 1 ms end.

  • Timestamps in the response are epoch milliseconds.

  • This at-time variant is not exposed as an action type in syslib.api-actions; it is reachable only via the standard/advanced endpoint or direct Lua.

  • For raw point-by-point reads over a time range (rather than at a single time), use syslib.api-readrawhistoricaldata; for aggregated/processed reads use syslib.api-readhistoricaldata.