API Read Historical Data

Read aggregated (processed) historical data over a time range for one or many items, divided into a fixed number of intervals, using a history aggregate (interpolative, average, min/max, raw, etc.).

Purpose

Exposes the functionality as the Web API ReadHistoricalData endpoint. For a [start_time, end_time] range split into intervals_no intervals, each item is aggregated with a chosen aggregate and returned as interval data. Calls are grouped by resolved data store while preserving result order. READ permission is checked per item.

Invocation Modes

HTTP Endpoints

Standard endpoint:

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

Advanced endpoint:

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

Direct Lua

Via API index script:

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

Direct script library call:

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

Action Pipeline

Also invocable as the read-historical-data action type inside a syslib.api-actions pipeline (the action calls apiExec:readhistoricaldata). The action accepts convenience keys (starttime, endtime, numberOfIntervals, objspec/identifier, item) that are normalized into the standard start_time/end_time/items/intervals_no form. See Also invocable as the read action type inside a syslib.api-actions pipeline (the action calls apiExec:read). The action accepts convenience keys (path, item) that are normalized into the standard items form. See syslib.api-actions.

[
    {
        "type": "read-historical-data",
        "objspec": "/IO-Home/Examples/Demo Data/Process Data/DC0815",
        "starttime": "2026-06-30T00:00:00.000Z",
        "endtime": "2026-06-30T23:59:59.000Z",
        "numberOfIntervals": 2
    }
]

Example

Aggregate one item over a 24-hours range into 2 intervals (default aggregate AGG_TYPE_INTERPOLATIVE):

{
    "start_time": "2026-06-30T00:00:00.000Z",
    "end_time": "2026-06-30T23:59:59.000Z",
    "opt": { "intervals_no": 2 },
    "items": [
        { "p": "/IO-Home/Examples/Demo Data/Process Data/DC0815" }
    ]
}

Response (default processed shape — intervals is an array of { V, Q, T } item-values):

{
    "data": {
        "start_time": "2026-06-30T00:00:00.000Z",
        "end_time": "2026-06-30T23:59:59.000Z",
        "items": [
            {
                "aggregate": "AGG_TYPE_INTERPOLATIVE",
                "intervals": [
                    {
                        "Q": 17179869184,
                        "T": 1782777600000,
                        "V": 14.698556810082163
                    },
                    {
                        "Q": 17179869184,
                        "T": 1782820799500,
                        "V": 16.08119381522132
                    }
                ],
                "p": "/IO-Home/Examples/Demo Data/Process Data/DC0815"
            }
        ]
    }
}

Example Bank

Lowercase fields (fields_as_lowercase)

Returns v,q,t keys instead of V,Q,T (matching the raw-historical-data response style):

{
    "start_time": "2026-06-30T00:00:00.000Z",
    "end_time": "2026-06-30T23:59:59.000Z",
    "opt": { "intervals_no": 2, "fields_as_lowercase": true },
    "items": [
        { "p": "/IO-Home/Examples/Demo Data/Process Data/DC0815" }
    ]
}
{
    "data": {
        "start_time": "2026-06-30T00:00:00.000Z",
        "end_time": "2026-06-30T23:59:59.000Z",
        "items": [
            {
                "aggregate": "AGG_TYPE_INTERPOLATIVE",
                "intervals": [
                    {
                        "q": 17179869184,
                        "t": 1782777600000,
                        "v": 14.698556810082163
                    },
                    {
                        "q": 17179869184,
                        "t": 1782820799500,
                        "v": 16.08119381522132
                    }
                ],
                "p": "/IO-Home/Examples/Demo Data/Process Data/DC0815"
            }
        ]
    }
}

Column-array response shape (res_as_item_values: false)

Returns intervals as parallel V/Q/T arrays instead of an array of objects:

{
    "start_time": "2026-06-30T00:00:00.000Z",
    "end_time": "2026-06-30T23:59:59.000Z",
    "opt": { "intervals_no": 2, "res_as_item_values": false },
    "items": [
        { "p": "/IO-Home/Examples/Demo Data/Process Data/DC0815" }
    ]
}
{
    "data": {
        "start_time": "2026-06-30T00:00:00.000Z",
        "end_time": "2026-06-30T23:59:59.000Z",
        "items": [
            {
                "aggregate": "AGG_TYPE_INTERPOLATIVE",
                "intervals": {
                    "Q": [
                        17179869184,
                        17179869184
                    ],
                    "T": [
                        1782777600000,
                        1782820799500
                    ],
                    "V": [
                        14.698556810082163,
                        16.08119381522132
                    ]
                },
                "p": "/IO-Home/Examples/Demo Data/Process Data/DC0815"
            }
        ]
    }
}

Multiple items with different aggregates

{
    "start_time": "2026-06-30T00:00:00.000Z",
    "end_time": "2026-06-30T23:59:59.000Z",
    "opt": { "intervals_no": 2},
    "items": [
        { "p": "/IO-Home/Examples/Demo Data/Process Data/DC0815", "aggregate": "AGG_TYPE_AVERAGE" },
        { "p": "/IO-Home/Examples/Demo Data/Process Data/FC0815", "aggregate": "AGG_TYPE_MINIMUM" },
        { "i": "8a1f3c0e-2b4d-4e6f-9a1b-0c2d4e6f8a1b", "aggregate": "AGG_TYPE_RAW" }
    ]
}

Direct Lua

local api = require('syslib.api')
local result, quality = api:readhistoricaldata({
    start_time = "2026-06-30T00:00:00.000Z",
    end_time = "2026-06-30T23:59:59.000Z",
    opt = { intervals_no = 2 },
    items = {
        { p = "/IO-Home/Examples/Demo Data/Process Data/DC0815" }
    }
}, req, hlp)

Request Contract

Top-level argument (SysLib.API-ReadHistoricalData.Arg):

Field Type Required Default Behavior

start_time

integer or string

yes

—

Range start. Epoch milliseconds or ISO 8601 string. Must be ≥ 0.

end_time

integer or string

yes

—

Range end. Epoch milliseconds or ISO 8601 string. Must be ≥ 0 and greater than start_time.

items

array

yes

—

Array of query items. Must be a non-empty array.

opt

object

no

—

Options (see below). Options may also be supplied at the top level.

Per-item object (SysLib.API-ReadHistoricalData.Arg-Query-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).

aggregate

string

no

AGG_TYPE_INTERPOLATIVE

History aggregate code (uppercased). Validated against syslib.model.codes.Aggregates.

Options (opt):

Field Type Required Default Behavior

intervals_no

integer

no

100

Number of intervals the range is split into.

partial_interval_treatment

string

no

"UASTANDARD"

How partial (incomplete) intervals are treated.

percentage_good

integer

no

100

Minimum percentage of good data for an interval to be good.

percentage_bad

integer

no

100

Percentage of bad data threshold.

treat_uncertain_as_bad

boolean

no

false

Count uncertain samples as bad.

sloped_extrapolation

boolean

no

false

Use sloped extrapolation at interval edges.

data_store

string

no

resolved per item

Data store to read from. When omitted, the default store is resolved per item and reads are grouped by store.

time_zone

string

no

"UTC"

UTC or UTC±00:00 → ISO9601 formatted timestamp; epoch → numeric ms timestamps.

modified_data_mode

boolean

no

—

Read modified-data series.

fields_as_lowercase

boolean

no

false

Use v,q,t keys instead of V,Q,T.

res_as_item_values

boolean

no

—

Response shape switch (see Response Contract).

processed_as_item_values

boolean

no

true

Deprecated — use res_as_item_values.

raw_as_item_values

boolean

no

false

Deprecated — use res_as_item_values.

Response Contract

Returns a single object with a data key, that contains an object with the following keys:

Field Type Meaning

start_time

integer

Resolved epoch start.

end_time

integer

Resolved epoch end.

items

array

One result per request item, in request order.

Each result item carries p (path), aggregate, and either intervals (on success) or error (on failure; also echoes i).

intervals shape depends on res_as_item_values and the aggregate:

Setting intervals shape

default / res_as_item_values: true

Array of item-value objects: [ { V, Q, T }, …​ ] (or v,q,t with fields_as_lowercase).

res_as_item_values: false

Column arrays: { V: […​], Q: […​], T: […​] }.

AGG_TYPE_RAW

Raw VQT data; with column-array mode each interval becomes a nested { V, Q, T } group.

Aggregate notes

  • AGG_TYPE_BESTFIT and AGG_TYPE_SAMPLE are composite aggregates computed from min/max (and interpolative for BestFit) sub-queries, then emitted in chronological order per interval.

  • Any aggregate in syslib.model.codes.Aggregates is accepted (e.g. AGG_TYPE_INTERPOLATIVE, AGG_TYPE_AVERAGE, AGG_TYPE_MINIMUM, AGG_TYPE_MAXIMUM, AGG_TYPE_RAW).

Permissions

  • Each item requires READ permission on the target object; otherwise that item is returned with an error and no intervals.

  • Runs in the context of the authenticated user.

Error Handling

  • Missing/invalid start_time or end_time, or end_time ⇐ start_time, raises an assertion/error for the whole request.

  • Per-item failures are captured as an error object on that item (others still return). Common messages: Missing path or identifier., Missing aggregate., Aggregate '<x>' is invalid, Invalid Object ID type '<type>'. …​, Path could not be resolved.

  • gethistory failures are caught (pcall) and surfaced as the item’s error.

Notes

  • Endpoint vs action key names differ. Standard endpoint: start_time, end_time, items[], opt.intervals_no. The read-historical-data action accepts starttime, endtime, objspec/item, numberOfIntervals and normalizes them — do not assume those camelCase keys on the standard endpoint.

  • processed_as_item_values and raw_as_item_values are deprecated; res_as_item_values overrules them.

  • Timestamps in the response are epoch milliseconds

  • Reads without an explicit data_store are grouped by each item’s resolved default store for efficiency, with original result order preserved.

  • Callbacks (willReadHistoricalDataForItem, willAppendIntervalDataPoint, didReadHistoricalDataForItem, didReadHistoricalData) exist for Lua-embedding scenarios and are not part of the HTTP contract.

  • For raw (unaggregated) point-by-point reads, use syslib.api-readrawhistoricaldata.