history.get

Description

integer/array history.get(object **parameters**)

The method allows to retrieve history data according to the given parameters.

See also: known issues

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.

ParameterTypeDescription
historyintegerHistory object types to return.

Possible values:
0 - numeric float;
1 - character;
2 - log;
3 - numeric unsigned;
4 - text.

Default: 3.
hostidsstring/arrayReturn only history from the given hosts.
itemidsstring/arrayReturn only history from the given items.
time_fromtimestampReturn only values that have been received after or at the given time.
time_tilltimestampReturn only values that have been received before or at the given time.
sortfieldstring/arraySort the result by the given properties.

Possible values are: itemid and clock.
countOutputbooleanThese parameters being common for all get methods are described in detail in the reference commentary page.
editableboolean
excludeSearchboolean
filterobject
limitinteger
outputquery
searchobject
searchByAnyboolean
searchWildcardsEnabledboolean
sortorderstring/array
startSearchboolean

Return values

(integer/array) Returns either:

  • an array of objects;

  • the count of retrieved objects, if the countOutput parameter has been used.

Examples

Retrieving item history data

Return 10 latest values received from a numeric(float) item.

Request:

  1. {
  2.     "jsonrpc": "2.0",
  3.     "method": "history.get",
  4.     "params": {
  5.         "output": "extend",
  6.         "history": 0,
  7.         "itemids": "23296",
  8.         "sortfield": "clock",
  9.         "sortorder": "DESC",
  10.         "limit": 10
  11.     },
  12.     "auth": "038e1d7b1735c6a5436ee9eae095879e",
  13.     "id": 1
  14. }

Response:

  1. {
  2.     "jsonrpc": "2.0",
  3.     "result": [
  4.         {
  5.             "itemid": "23296",
  6.             "clock": "1351090996",
  7.             "value": "0.0850",
  8.             "ns": "563157632"
  9.         },
  10.         {
  11.             "itemid": "23296",
  12.             "clock": "1351090936",
  13.             "value": "0.1600",
  14.             "ns": "549216402"
  15.         },
  16.         {
  17.             "itemid": "23296",
  18.             "clock": "1351090876",
  19.             "value": "0.1800",
  20.             "ns": "537418114"
  21.         },
  22.         {
  23.             "itemid": "23296",
  24.             "clock": "1351090816",
  25.             "value": "0.2100",
  26.             "ns": "522659528"
  27.         },
  28.         {
  29.             "itemid": "23296",
  30.             "clock": "1351090756",
  31.             "value": "0.2150",
  32.             "ns": "507809457"
  33.         },
  34.         {
  35.             "itemid": "23296",
  36.             "clock": "1351090696",
  37.             "value": "0.2550",
  38.             "ns": "495509699"
  39.         },
  40.         {
  41.             "itemid": "23296",
  42.             "clock": "1351090636",
  43.             "value": "0.3600",
  44.             "ns": "477708209"
  45.         },
  46.         {
  47.             "itemid": "23296",
  48.             "clock": "1351090576",
  49.             "value": "0.3750",
  50.             "ns": "463251343"
  51.         },
  52.         {
  53.             "itemid": "23296",
  54.             "clock": "1351090516",
  55.             "value": "0.3150",
  56.             "ns": "447947017"
  57.         },
  58.         {
  59.             "itemid": "23296",
  60.             "clock": "1351090456",
  61.             "value": "0.2750",
  62.             "ns": "435307141"
  63.         }
  64.     ],
  65.     "id": 1
  66. }

Source

CHistory::get() in ui/include/classes/api/services/CHistory.php.