API Event Read History

Read historized alarm & event (A&E) documents over a time range for one or many event-stream objects, with optional MongoDB-style filter, sort, projection, paging, and document transformation.

Purpose

Exposes the functionality as the Web API Read Event History endpoint. For a [start_time, end_time] range, each requested event-stream object is queried for its historized A&E documents. Queries may be batched (queries[]). A MongoDB document filter, sort, and projection can be applied, along with skip/limit paging and a transformation that controls the returned document shape. READ permission is checked per event-stream object; the target event data store type is validated as an EventDataStore.

Invocation Modes

HTTP Endpoints

Standard endpoint:

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

Advanced endpoint:

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

Direct Lua

Via API index script:

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

Direct script library call:

local evtApi = require('syslib.api-event-readhistory')
local result = evtApi:readeventhistory(arg, req, hlp)

Example

Read all events for one event-stream object over a one-hour range (default limit 1000, default transformation none → raw event documents):

{
    "start_time": "2026-04-15T10:00:00.000Z",
    "end_time": "2026-04-15T11:00:00.000Z",
    "items": [
        { "p": "/IO-Home/Examples/Demo Data/Home Alarms Stream" }
    ]
}

Response:

{
    "data": {
        "event_data": {
            "query_data": [
                {
                    "query_index": "1",
                    "start_time": "2026-04-15T10:00:00.000Z",
                    "end_time": "2026-04-15T11:00:00.000Z",
                    "items": [
                        {
                            "i": "8a1f3c0e-2b4d-4e6f-9a1b-0c2d4e6f8a1b",
                            "p": "/IO-Home/Examples/Demo Data/Home Alarms Stream",
                            "name": "Home Alarms Stream",
                            "events": [
                                {
                                    "_id": "69df62745383d7a48e092004",
                                    "e_": {
                                        "c_": { "m": "EVENT", "t": 1776247384023 },
                                        "s_": { "i": 1234, "o": 1048576, "t": 1776247384023 },
                                        "o_": {
                                            "h_": {
                                                "c_": { "c": 0, "t": "Process" },
                                                "n": 1, "o": 0, "q": 0,
                                                "r_": { "c": 700, "t": "High" }
                                            }
                                        }
                                    }
                                }
                            ]
                        }
                    ]
                }
            ]
        }
    }
}

Example Bank

Filter by a custom attribute (MongoDB document)

filter, sort, and project are JSON objects (MongoDB query documents), not strings. Operators may be written as $gt or, for Web Studio mingo compatibility, as $gt (the leading is stripped server-side):

{
    "start_time": "2026-04-15T00:00:00.000Z",
    "end_time": "2026-04-15T23:59:59.999Z",
    "items": [ { "p": "/IO-Home/Examples/Demo Data/Home Alarms Stream" } ],
    "filter": {
        "e_.o_.a_.a_": { "$elemMatch": { "l": "SourcePath", "d_.v": "/IO-Home/Examples/Demo Data/Events Data/Sine Wave Home/Level Alarm Sine Wave Home" } }
    },
    "limit": 20
}

Sort and project specific fields

project maps to the underlying projection option. Projection and transformation are mutually exclusive.

{
    "start_time": "2026-04-15T00:00:00.000Z",
    "end_time": "2026-04-15T23:59:59.999Z",
    "items": [ { "p": "/IO-Home/Examples/Demo Data/Home Alarms Stream" } ],
    "sort": { "e_.c_.t": -1 },
    "project": { "e_.c_.t": 1, "e_.s_.o": 1, "_id": 0 },
    "skip": 0,
    "limit": 50
}
{
    "data": {
        "event_data": {
            "query_data": [
                {
                    "query_index": "1",
                    "start_time": "2026-04-15T00:00:00.000Z",
                    "end_time": "2026-04-15T23:59:59.999Z",
                    "items": [
                        {
                            "i": "8a1f3c0e-2b4d-4e6f-9a1b-0c2d4e6f8a1b",
                            "p": "/IO-Home/Examples/Demo Data/Home Alarms Stream",
                            "name": "Home Alarms Stream",
                            "events": [
                                { "e_": { "c_": { "t": 1776247384023 }, "s_": { "o": 1048576 } } }
                            ]
                        }
                    ]
                }
            ]
        }
    }
}

Readable transformation (flattened attributes)

transformation accepts none (default), readable, readable_lc, kv, and kv_lc. With readable the document carries friendly attr keys instead of the nested e_ codes:

{
    "start_time": "2026-04-15T00:00:00.000Z",
    "end_time": "2026-04-15T23:59:59.999Z",
    "items": [ { "p": "/IO-Home/Examples/Demo Data/Home Alarms Stream" } ],
    "transformation": "readable",
    "limit": 1
}
{
    "data": {
        "event_data": {
            "query_data": [
                {
                    "query_index": "1",
                    "start_time": "2026-04-15T00:00:00.000Z",
                    "end_time": "2026-04-15T23:59:59.999Z",
                    "items": [
                        {
                            "i": "8a1f3c0e-2b4d-4e6f-9a1b-0c2d4e6f8a1b",
                            "p": "/IO-Home/Examples/Demo Data/Home Alarms Stream",
                            "name": "Home Alarms Stream",
                            "events": [
                                {
                                    "_id": "69df62745383d7a48e092004",
                                    "e_": {
                                        "c_common": {
                                            "mmessage": "HHH Alarm value = 95.015939 limit = 95.000000",
                                            "ttimestamp": 1782863977703
                                        },
                                        "o_opcevent": {
                                            "h_header": {
                                                "x_source": {
                                                    "iitemid": "Level Alarm Sine Wave Home"
                                                }
                                            }
                                        }
                                    }
                                }
                            ]
                        }
                    ]
                }
            ]
        }
    }
}

Batched queries

Multiple independent queries in one request. Each query is processed separately; results are returned in query_data in query order, each carrying its query_index.

{
    "queries": [
        {
            "query_index": "active",
            "start_time": "2026-04-15T00:00:00.000Z",
            "end_time": "2026-04-15T23:59:59.999Z",
            "items": [ { "p": "/IO-Home/Local/opc.tcp/es1" } ]
        },
        {
            "query_index": "history",
            "start_time": "2026-04-01T00:00:00.000Z",
            "end_time": "2026-04-14T23:59:59.999Z",
            "items": [ { "i": "9b2c4d6e-3a5f-4071-8c2d-1e3f5a7b9c0d" } ]
        }
    ]
}

Explicit data store(s)

data_store may be a single store applied to every item, or an array whose length must equal the items array:

{
    "start_time": "2026-04-15T00:00:00.000Z",
    "end_time": "2026-04-15T23:59:59.999Z",
    "items": [
        { "p": "/IO-Home/Local/opc.tcp/es1" },
        { "p": "/IO-Home/Local/opc.tcp/es2" }
    ],
    "data_store": [ "/IO-Home/EventStore1", "/IO-Home/EventStore2" ]
}

Direct Lua

local api = require('syslib.api')
local result = api:readeventhistory({
    start_time = "2026-04-15T00:00:00.000Z",
    end_time = "2026-04-15T23:59:59.999Z",
    items = { { p = "/IO-Home/Examples/Demo Data/Home Alarms Stream" } },
    filter = {
        ["e_.o_.a_.a_"] = { ["$elemMatch"] = { l = "SourcePath", ["d_.v"] = "/IO-Home/Examples/Demo Data/Events Data/Sine Wave Home/Level Alarm Sine Wave Home" } }
    },
    limit = 20
}, req, hlp)

Request Contract

Top-level argument (SysLib.API-Event-ReadHistory.Arg). The top-level object is itself a single query; supply queries[] to batch several:

Field Type Required Default Behavior

queries

array

no

—

Array of query objects (each with the per-query fields below). When omitted, the top-level object is treated as one query.

Per-query object (SysLib.API-Event-ReadHistory.Query):

Field Type Required Default Behavior

start_time

integer or string

yes

—

Range start. Unix epoch milliseconds or ISO 8601 string. Must be ≥ 0. Alias starttime is also accepted.

end_time

integer or string

yes

—

Range end. Unix epoch milliseconds or ISO 8601 string. Must be ≥ 0. Alias endtime is also accepted.

items

array

yes

—

Event-stream objects to query. Must be a non-empty array (else 412).

data_store

string or string[]

no

resolved per item

Event data store(s). A single value is applied to every item; an array must match items length (else error). When omitted, each item’s default store is resolved via syslib.getdefaultstore.

filter

object

no

—

MongoDB query document selecting matching events. JSON-encoded server-side; _$op is normalized to $op.

sort

object

no

—

MongoDB sort document. JSON-encoded server-side.

project

object

no

—

MongoDB projection document (passed to geteventhistory as projection). Cannot be combined with a transformation other than none.

skip

integer

no

—

Number of matching documents to skip before returning results.

limit

integer

no

1000

Maximum number of event documents returned per item.

transformation

string

no

none

Output document shape: none, readable, readable_lc, kv, kv_lc. Mutually exclusive with project.

time_out

integer

no

0

Query timeout. Alias tim is resolved first, then time_out.

query_index

string

no

position index

Echoed back on the query’s result. Defaults to the 1-based query position as a string.

Per-item object (SysLib.API-Event-ReadHistory.Query-Item):

Field Type Required Default Behavior

p

string

conditional

—

Event-stream object path. One of p or i is required (p is preferred when both are present).

i

string

conditional

—

Event-stream object ID.

Response Contract

Returns a single object with data key, with the value of type event_data. This is an object whose query_data is an array with one entry per query.

Field Type Meaning

event_data.query_data

array

One result per query, in request order.

Each query_data entry (SysLib.API-Event-ReadHistory.QueryData):

Field Type Present when

query_index

string

always (echoed/derived)

start_time

string (ISO 8601)

query succeeded

end_time

string (ISO 8601)

query succeeded

items

array

query succeeded

error

object { msg, code }

the whole query failed

Each item in query_data.items (SysLib.API-Event-ReadHistory.QueryData-Item):

Field Type Present when

i

string

resolved (event-stream object GUID)

p

string

resolved (event-stream object path)

name

string

resolved (event-stream ObjectName)

events

array

read succeeded — the event documents

error

unknown

this item’s geteventhistory read failed

Each entry of events is an A&E event document as returned by syslib.geteventhistory. With the default none transformation the document uses the nested coded schema (id, e.c_ common, e_.s_ system, e_.o_ OPC Classic event, e_.u_ OPC UA event); the readable/kv transformations add flattened attr keys. See the syslib.geteventhistory event document schema for the full field tree.

Permissions

  • Each item requires READ permission on the target event-stream object (hlp:checkpermission); a denial returns the query with an error carrying the permission status_code.

  • The target event data store is validated as an EventDataStore class instance. Store-type checks are skipped when the user lacks permission to inspect the system model (the message ends with permission denied), so restricted users can still read events.

  • Permission checks on the (custom) data store level itself were removed (20231023.6).

  • Runs in the context of the authenticated user.

Error Handling

Query-level failures return the whole query with an error { msg, code }; the other queries in a batch still return.

Condition Code Message

items not an array / empty

412

Illegal query, 'items' is not an array or doesn’t contain object paths/ids.

data_store array length ≠ items length

412

Invalid data_store specification. Expected an array matching that of items

Bad event data store quality

—

error from checkDataStoreType

Store check raised (non-permission)

500

underlying error

Missing/invalid start_time/end_time

412

Argument 'start_time' is missing. / Value '<x>' of 'start_time' argument is invalid. (and end_time equivalents)

Item missing p and i

412

Missing event stream object path or identifier.

READ permission denied

item’s status_code

Item '<spec>'; <permission error>

Invalid option type (e.g. filter not a table)

412

Invalid argument '<name>'. Must be a <type>.

transformation set together with project

412

Transformation can’t be used when 'projection' is also specified.

Unexpected query failure

500

Unknown error has occurred: <err>

  • arg must be a Lua table (asserts otherwise).

  • Per-item reads use a protected call (pcall syslib.geteventhistory). A read failure is captured as that item’s error. If no item in the query read successfully, the query raises (surfacing the first item error such as item=<path> error=<…​>) rather than returning partial empties.

Notes

  • Standard endpoint route. The HTTP route segment and the script-library function are both readeventhistory.

  • filter/sort/project are objects, not strings. Send filter, sort, and project as JSON objects on the HTTP endpoint (Lua tables in direct Lua); the endpoint JSON-encodes them internally.

  • Mingo operator workaround. When encoding filter/sort/project, a leading before a $ operator key is stripped ("$gt" → "$gt"), accommodating Web Studio aggregate pipelines. Plain $ operators are unaffected.

  • project maps to projection. The request key is project; it is forwarded to geteventhistory as projection and cannot be combined with a non-none transformation.

  • Response shape. event_data is a single object whose query_data field holds the array of results — read result.event_data.query_data[].

  • Time aliases. Both start_time/end_time and starttime/endtime are accepted; values may be epoch milliseconds or ISO 8601 and are normalized to ISO 8601 in the response.

  • limit defaults to 1000 and time_out to 0; the tim alias for time_out is resolved first.

  • For the full event document field tree (e_.s_, e_.c_, e_.o_, e_.u_, custom attributes), see the syslib.geteventhistory reference.