Read Event History
-
Reads event
-
Required security permission - READ (On the event object and custom data store if referenced).
-
HTTP methods supported: GET, POST.
-
Transform, Filter and Sort Output.
Description
This endpoint exposes the geteventhistory
function available in the syslib
library used to retrieve stored events.
Parameters
Name | Type | Optional | Description | ||
---|---|---|---|---|---|
start_time |
string |
no |
The start time (UTC) of the interval to retrieve data for. |
||
end_time |
string |
no |
The end time (UTC) of the interval to retrieve data for. |
||
identifier |
string or integer |
no |
The path or ID of the event object to be queried for historical information. When using the POST method, an array of identifiers can be provided. |
||
data_store |
string |
yes |
Specifies a data store for the query operation. If not specified, this defaults to the System Event Data Store for Master Cores. For Local Cores, this option is required. The value should be an |
||
filter |
string |
yes |
To retrieve the event data, a MongoDB "find" call is made. Refer to the MongoDB documentation for details on how to compose filter query expressions. The JSON query expression must be Base64 encoded for use in the url. |
||
sort |
string |
yes |
A MongoDB document as a JSON (dictionary), which specifies sorting for the returned documents. The syntax is identical to the MongoDB sort expression syntax. The JSON sort expression must be Base64 encoded for use in the url. |
||
project |
string |
yes |
A JSON document defining the MongoDB project expression, which specifies the fields to include or exclude from the result set. The JSON project expression must be Base64 encoded for use in the url. |
||
limit |
integer |
yes |
Caps the count of returned events to the number specified. If the limit is not provided, all matching events are retrieved. |
||
skip |
integer |
yes |
Skips over the first "n" matched events. |
||
transformation |
string |
yes |
String indicating the format of the returned data. Options are:
|
||
insights |
boolean |
yes |
Indicates application insights should be included in the response, by default false. |
Example
Get the last two events generated by a specific source .
This example shows how to use the readeventhistory
API-call to retrieve the last two events raised from any source object with a path starting with /System/Core/Examples
To do so, we will need to provide the following parameters:
-
Mandatory parameters:
-
identifier: In this scenario, the
/System/Core/Examples/Demo Data/Events/ScriptEvent1
event object is used. -
Start and end times: Select an time span of one hour using ISO UTC strings such as "2021-12-08T17:00:00Z" and "2021-12-08T18:00:00Z"
-
-
Optional parameters:
-
filter: The filter expression will ensure that only the required subset of events are considered.
{ "e_.o_.h_.x_.i" : { "$regex" : "^/System/Core/Examples", "$options" : "" } }
-
sort: Sort the events in descending time order so the most recent ones are at the top.
{ "e_.s_.t": -1 }
-
limit: Restrict the query to return only 2 elements.
-
project: To keep the output concise, we’ll remove the
_id
field from the output, and explicitly ask for the timestamp, message and source tags{ "_id": 0, "e_.o_.h_.x_.i": 1, "e_.s_.t": 1, "e_.c_.m": 1 }
-
HTTP POST
Let’s consider the POST method first, since it is the easiest to configure:
Request body
{
"items": [
{
"p": "/System/Core/Examples/Demo Data/Events/ScriptEvent1"
}
],
"start_time" : "2021-12-08T17:00:00Z",
"end_time" : "2021-12-08T18:00:00Z",
"filter" : {
"e_.o_.h_.x_.i" : {
"$regex" : "^/System/Core/Examples",
"$options" : ""
}
},
"project" : {
"_id": 0,
"e_.o_.h_.x_.i": 1,
"e_.s_.t": 1,
"e_.c_.m": 1
},
"sort" : {
"e_.s_.t": -1
}
}
Response body
{
"items": [
{
"events": [
{
"e_": {
"s_": {
"t": {
"$date": "2021-12-10T15:21:17.308+0100"
}
},
"c_": {
"m": "script event generator 130.497192382813"
},
"o_": {
"h_": {
"x_": {
"i": "/System/Core/Examples/Demo Data/Events/ScriptEventGenerator1"
}
}
}
}
}
]
},
{
"e_": {
"s_": {
"t": {
"$date": "2021-12-10T15:22:17.312+0100"
}
},
"c_": {
"m": "script event generator 129.135864257813"
},
"o_": {
"h_": {
"x_": {
"i": "/System/Core/Examples/Demo Data/Events/ScriptEventGenerator1"
}
}
}
}
}
]
}
HTTP GET
To make the same call using an HTTP GET, all the query parameters need to be provided in the url and the JSON ones have to be Base64 encoded. This results in the in the following URL
Request URL
-
api/v2/readeventhistory?
start_time=2021-12-08T17%3A00%3A00Z&
end_time=2021-12-08T17%3A01%3A00Z&
identifier=%2FSystem%2FCore%2FExamples%2FDemo%20Data%2FEvents%2FScriptEvent1&
filter=eyAKICAgICJlXy5vXy5oXy54Xy5pIiA6IHsgCiAgICAgICAgIiRyZWdleCIgOiAiXi9TeXN0ZW0vQ29yZS9FeGFtcGxlcyIsCiAgICAgICAgIiRvcHRpb25zIiA6ICIiICAKICAgIH0gCn0g&
sort=eyAKICAgICJlXy5zXy50IjogLTEKfQ%3D%3D&
project=eyAKICAgICJfaWQiOiAwLAogICAgImVfLm9fLmhfLnhfLmkiOiAxLCAKICAgICJlXy5zXy50IjogMSwgCiAgICAiZV8uY18ubSI6IDEgCn0%3D&limit=1&transformation=%22readable%22