Table of Contents
history.get
Description
integer/array history.get(object parameters)
The method allows to retrieve history data according to the given parameters.
This method may return historical data of a deleted entity if this data has not been removed by the housekeeper yet.
This method is available to users of any type. Permissions to call the method can be revoked in user role settings. See User roles for more information.
Parameters
(object) Parameters defining the desired output.
The method supports the following parameters.
| Parameter | Type | Description |
|---|---|---|
| history | integer | History object types to return. Possible values: 0 - numeric float; 1 - character; 2 - log; 3 - (default) numeric unsigned; 4 - text; 5 - binary; 6 - JSON. |
| hostids | ID/array | Return only history from the given hosts. |
| itemids | ID/array | Return only history from the given items. |
| maxValueSize | integer | Maximum number of bytes to return in the value property.Possible values range: 1-134217728 (1 byte to 128MiB). If set to null, no limit is applied.Default: 65536 (64KiB). Parameter behavior: - supported if history is set to "binary" or "JSON" |
| time_from | timestamp | Return only values that have been received after or at the given time. |
| time_till | timestamp | Return only values that have been received before or at the given time. |
| sortfield | string/array | Sort the result by the given properties. Possible values: itemid, clock, ns. |
| search | object | Return results that match the given pattern (case-insensitive). Accepts an object, where the keys are property names, and the values are strings to search for. If no additional options are given, this will perform a LIKE "%…%" search.Does not support searching by value if history is set to 6 (JSON). |
| countOutput | boolean | These parameters are described in the reference commentary. |
| editable | boolean | |
| excludeSearch | boolean | |
| filter | object | |
| limit | integer | |
| output | query | |
| searchByAny | boolean | |
| searchWildcardsEnabled | boolean | |
| sortorder | string/array | |
| startSearch | boolean |
Return values
(integer/array) Returns either:
- an array of objects;
- the count of retrieved objects, if the
countOutputparameter has been used.
Examples
Retrieving item history data
Return 10 latest values received from a numeric(float) item.
{
"jsonrpc": "2.0",
"method": "history.get",
"params": {
"output": "extend",
"history": 0,
"itemids": "23296",
"sortfield": "clock",
"sortorder": "DESC",
"limit": 10
},
"id": 1
}Response:
{
"jsonrpc": "2.0",
"result": [
{
"itemid": "23296",
"clock": "1351090996",
"value": "0.085",
"ns": "563157632"
},
{
"itemid": "23296",
"clock": "1351090936",
"value": "0.16",
"ns": "549216402"
},
{
"itemid": "23296",
"clock": "1351090876",
"value": "0.18",
"ns": "537418114"
},
{
"itemid": "23296",
"clock": "1351090816",
"value": "0.21",
"ns": "522659528"
},
{
"itemid": "23296",
"clock": "1351090756",
"value": "0.215",
"ns": "507809457"
},
{
"itemid": "23296",
"clock": "1351090696",
"value": "0.255",
"ns": "495509699"
},
{
"itemid": "23296",
"clock": "1351090636",
"value": "0.36",
"ns": "477708209"
},
{
"itemid": "23296",
"clock": "1351090576",
"value": "0.375",
"ns": "463251343"
},
{
"itemid": "23296",
"clock": "1351090516",
"value": "0.315",
"ns": "447947017"
},
{
"itemid": "23296",
"clock": "1351090456",
"value": "0.275",
"ns": "435307141"
}
],
"id": 1
}Source
CHistory::get() in ui/include/classes/api/services/CHistory.php.