item.get

Description

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

The method allows to retrieve items according to the given parameters.

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
itemidsstring/arrayReturn only items with the given IDs.
groupidsstring/arrayReturn only items that belong to the hosts from the given groups.
templateidsstring/arrayReturn only items that belong to the given templates.
hostidsstring/arrayReturn only items that belong to the given hosts.
proxyidsstring/arrayReturn only items that are monitored by the given proxies.
interfaceidsstring/arrayReturn only items that use the given host interfaces.
graphidsstring/arrayReturn only items that are used in the given graphs.
triggeridsstring/arrayReturn only items that are used in the given triggers.
applicationidsstring/arrayReturn only items that belong to the given applications.
webitemsflagInclude web items in the result.
inheritedbooleanIf set to true return only items inherited from a template.
templatedbooleanIf set to true return only items that belong to templates.
monitoredbooleanIf set to true return only enabled items that belong to monitored hosts.
groupstringReturn only items that belong to a group with the given name.
hoststringReturn only items that belong to a host with the given name.
applicationstringReturn only items that belong to an application with the given name.
withtriggersbooleanIf set to true return only items that are used in triggers.
selectHostsqueryReturn a hosts property with an array of hosts that the item belongs to.
selectInterfacesqueryReturn an interfaces property with an array of host interfaces used by the item.
selectTriggersqueryReturn a triggers property with the triggers that the item is used in.

Supports count.
selectGraphsqueryReturn a graphs property with the graphs that contain the item.

Supports count.
selectApplicationsqueryReturn an applications property with the applications that the item belongs to.
selectDiscoveryRulequeryReturn a discoveryRule property with the LLD rule that created the item.
selectItemDiscoveryqueryReturn an itemDiscovery property with the item discovery object. The item discovery object links the item to an item prototype from which it was created.

It has the following properties:
itemdiscoveryid - (string) ID of the item discovery;
itemid - (string) ID of the discovered item;
parent_itemid - (string) ID of the item prototype from which the item has been created;
key - (string) key of the item prototype;
lastcheck - (timestamp) time when the item was last discovered;
tsdelete - (timestamp) time when an item that is no longer discovered will be deleted.
selectPreprocessingqueryReturn a preprocessing property with item preprocessing options.

It has the following properties:
type - (string) The preprocessing option type:
1 - Custom multiplier;
2 - Right trim;
3 - Left trim;
4 - Trim;
5 - Regular expression matching;
6 - Boolean to decimal;
7 - Octal to decimal;
8 - Hexadecimal to decimal;
9 - Simple change;
10 - Change per second;
11 - XML XPath;
12 - JSONPath;
13 - In range;
14 - Matches regular expression;
15 - Does not match regular expression;
16 - Check for error in JSON;
17 - Check for error in XML;
18 - Check for error using regular expression;
19 - Discard unchanged;
20 - Discard unchanged with heartbeat;
21 - JavaScript;
22 - Prometheus pattern;
23 - Prometheus to JSON;
24 - CSV to JSON;
25 - Replace.

params - (string) Additional parameters used by preprocessing option. Multiple parameters are separated by LF (\n)character.
error_handler - (string) Action type used in case of preprocessing step failure:
0 - Error message is set by Zabbix server;
1 - Discard value;
2 - Set custom value;
3 - Set custom error message.

error_handler_params - (string) Error handler parameters.
filterobjectReturn only those results that exactly match the given filter.

Accepts an array, where the keys are property names, and the values are either a single value or an array of values to match against.

Supports additional filters:
host - technical name of the host that the item belongs to.
limitSelectsintegerLimits the number of records returned by subselects.

Applies to the following subselects:
selectGraphs - results will be sorted by name;
selectTriggers - results will be sorted by description.
sortfieldstring/arraySort the result by the given properties.

Possible values are: itemid, name, key, delay, history, trends, type and status.
countOutputbooleanThese parameters being common for all get methods are described in detail in the reference commentary page.
editableboolean
excludeSearchboolean
limitinteger
outputquery
preservekeysboolean
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

Finding items by key

Retrieve all items from host with ID “10084” that have the word “system” in the key and sort them by name.

Request:

  1. {
  2.     "jsonrpc": "2.0",
  3.     "method": "item.get",
  4.     "params": {
  5.         "output": "extend",
  6.         "hostids": "10084",
  7.         "search": {
  8.             "key_": "system"
  9.         },
  10.         "sortfield": "name"
  11.     },
  12.     "auth": "038e1d7b1735c6a5436ee9eae095879e",
  13.     "id": 1
  14. }

Response:

  1. {
  2.     "jsonrpc": "2.0",
  3.     "result": [
  4.         {
  5.             "itemid": "23298",
  6.             "type": "0",
  7.             "snmp_oid": "",
  8.             "hostid": "10084",
  9.             "name": "Context switches per second",
  10.             "key_": "system.cpu.switches",
  11.             "delay": "1m",
  12.             "history": "7d",
  13.             "trends": "365d",
  14.             "lastvalue": "2552",
  15.             "lastclock": "1351090998",
  16.             "prevvalue": "2641",
  17.             "state": "0",
  18.             "status": "0",
  19.             "value_type": "3",
  20.             "trapper_hosts": "",
  21.             "units": "sps",
  22.             "error": "",
  23.             "logtimefmt": "",
  24.             "templateid": "22680",
  25.             "valuemapid": "0",
  26.             "params": "",
  27.             "ipmi_sensor": "",
  28.             "authtype": "0",
  29.             "username": "",
  30.             "password": "",
  31.             "publickey": "",
  32.             "privatekey": "",
  33.             "lastns": "564054253",
  34.             "flags": "0",
  35.             "interfaceid": "1",
  36.             "description": "",
  37.             "inventory_link": "0",
  38.             "lifetime": "0s",
  39.             "evaltype": "0",
  40.             "jmx_endpoint": "",
  41.             "master_itemid": "0",
  42.             "timeout": "3s",
  43.             "url": "",
  44.             "query_fields": [],
  45.             "posts": "",
  46.             "status_codes": "200",
  47.             "follow_redirects": "1",
  48.             "post_type": "0",
  49.             "http_proxy": "",
  50.             "headers": [],
  51.             "retrieve_mode": "0",
  52.             "request_method": "0",
  53.             "output_format": "0",
  54.             "ssl_cert_file": "",
  55.             "ssl_key_file": "",
  56.             "ssl_key_password": "",
  57.             "verify_peer": "0",
  58.             "verify_host": "0",
  59.             "allow_traps": "0",
  60.             "parameters": []
  61.         },
  62.         {
  63.             "itemid": "23299",
  64.             "type": "0",
  65.             "snmp_oid": "",
  66.             "hostid": "10084",
  67.             "name": "CPU $2 time",
  68.             "key_": "system.cpu.util[,idle]",
  69.             "delay": "1m",
  70.             "history": "7d",
  71.             "trends": "365d",
  72.             "lastvalue": "86.031879",
  73.             "lastclock": "1351090999",
  74.             "prevvalue": "85.306944",
  75.             "state": "0",
  76.             "status": "0",
  77.             "value_type": "0",
  78.             "trapper_hosts": "",
  79.             "units": "%",
  80.             "error": "",
  81.             "logtimefmt": "",
  82.             "templateid": "17354",
  83.             "valuemapid": "0",
  84.             "params": "",
  85.             "ipmi_sensor": "",
  86.             "authtype": "0",
  87.             "username": "",
  88.             "password": "",
  89.             "publickey": "",
  90.             "privatekey": "",
  91.             "lastns": "564256864",
  92.             "flags": "0",
  93.             "interfaceid": "1",
  94.             "description": "The time the CPU has spent doing nothing.",
  95.             "inventory_link": "0",
  96.             "lifetime": "0s",
  97.             "evaltype": "0",
  98.             "jmx_endpoint": "",
  99.             "master_itemid": "0",
  100.             "timeout": "3s",
  101.             "url": "",
  102.             "query_fields": [],
  103.             "posts": "",
  104.             "status_codes": "200",
  105.             "follow_redirects": "1",
  106.             "post_type": "0",
  107.             "http_proxy": "",
  108.             "headers": [],
  109.             "retrieve_mode": "0",
  110.             "request_method": "0",
  111.             "output_format": "0",
  112.             "ssl_cert_file": "",
  113.             "ssl_key_file": "",
  114.             "ssl_key_password": "",
  115.             "verify_peer": "0",
  116.             "verify_host": "0",
  117.             "allow_traps": "0",
  118.             "parameters": []
  119.         },
  120.         {
  121.             "itemid": "23300",
  122.             "type": "0",
  123.             "snmp_oid": "",
  124.             "hostid": "10084",
  125.             "name": "CPU $2 time",
  126.             "key_": "system.cpu.util[,interrupt]",
  127.             "history": "7d",
  128.             "trends": "365d",
  129.             "lastvalue": "0.008389",
  130.             "lastclock": "1351091000",
  131.             "prevvalue": "0.000000",
  132.             "state": "0",
  133.             "status": "0",
  134.             "value_type": "0",
  135.             "trapper_hosts": "",
  136.             "units": "%",
  137.             "error": "",
  138.             "logtimefmt": "",
  139.             "templateid": "22671",
  140.             "valuemapid": "0",
  141.             "params": "",
  142.             "ipmi_sensor": "",
  143.             "authtype": "0",
  144.             "username": "",
  145.             "password": "",
  146.             "publickey": "",
  147.             "privatekey": "",
  148.             "lastns": "564661387",
  149.             "flags": "0",
  150.             "interfaceid": "1",
  151.             "description": "The amount of time the CPU has been servicing hardware interrupts.",
  152.             "inventory_link": "0",
  153.             "lifetime": "0s",
  154.             "evaltype": "0",
  155.             "jmx_endpoint": "",
  156.             "master_itemid": "0",
  157.             "timeout": "3s",
  158.             "url": "",
  159.             "query_fields": [],
  160.             "posts": "",
  161.             "status_codes": "200",
  162.             "follow_redirects": "1",
  163.             "post_type": "0",
  164.             "http_proxy": "",
  165.             "headers": [],
  166.             "retrieve_mode": "0",
  167.             "request_method": "0",
  168.             "output_format": "0",
  169.             "ssl_cert_file": "",
  170.             "ssl_key_file": "",
  171.             "ssl_key_password": "",
  172.             "verify_peer": "0",
  173.             "verify_host": "0",
  174.             "allow_traps": "0",
  175.             "parameters": []
  176.         }
  177.     ],
  178.     "id": 1
  179. }

Finding dependent items by key

Retrieve all dependent items from host with ID “10116” that have the word “apache” in the key.

Request:

  1. {
  2.     "jsonrpc": "2.0",
  3.     "method": "item.get",
  4.     "params": {
  5.         "output": "extend",
  6.         "hostids": "10116",
  7.         "search": {
  8.             "key_": "apache"
  9.         },
  10.         "filter": {
  11.             "type": "18"
  12.         }
  13.     },
  14.     "auth": "038e1d7b1735c6a5436ee9eae095879e",
  15.     "id": 1
  16. }

Response:

  1. {
  2.     "jsonrpc": "2.0",
  3.     "result": [
  4.         {
  5.             "itemid": "25550",
  6.             "type": "18",
  7.             "snmp_oid": "",
  8.             "hostid": "10116",
  9.             "name": "Days",
  10.             "key_": "apache.status.uptime.days",
  11.             "delay": "",
  12.             "history": "90d",
  13.             "trends": "365d",
  14.             "status": "0",
  15.             "value_type": "3",
  16.             "trapper_hosts": "",
  17.             "units": "",
  18.             "formula": "",
  19.             "error": "",
  20.             "logtimefmt": "",
  21.             "templateid": "0",
  22.             "valuemapid": "0",
  23.             "params": "",
  24.             "ipmi_sensor": "",
  25.             "authtype": "0",
  26.             "username": "",
  27.             "password": "",
  28.             "publickey": "",
  29.             "privatekey": "",
  30.             "flags": "0",
  31.             "interfaceid": "0",
  32.             "description": "",
  33.             "inventory_link": "0",
  34.             "lifetime": "30d",
  35.             "state": "0",
  36.             "evaltype": "0",
  37.             "master_itemid": "25545",
  38.             "jmx_endpoint": "",
  39.             "timeout": "3s",
  40.             "url": "",
  41.             "query_fields": [],
  42.             "posts": "",
  43.             "status_codes": "200",
  44.             "follow_redirects": "1",
  45.             "post_type": "0",
  46.             "http_proxy": "",
  47.             "headers": [],
  48.             "retrieve_mode": "0",
  49.             "request_method": "0",
  50.             "output_format": "0",
  51.             "ssl_cert_file": "",
  52.             "ssl_key_file": "",
  53.             "ssl_key_password": "",
  54.             "verify_peer": "0",
  55.             "verify_host": "0",
  56.             "allow_traps": "0",
  57.             "lastclock": "0",
  58.             "lastns": "0",
  59.             "lastvalue": "0",
  60.             "prevvalue": "0",
  61.             "parameters": []
  62.         },
  63.         {
  64.             "itemid": "25555",
  65.             "type": "18",
  66.             "snmp_oid": "",
  67.             "hostid": "10116",
  68.             "name": "Hours",
  69.             "key_": "apache.status.uptime.hours",
  70.             "delay": "0",
  71.             "history": "90d",
  72.             "trends": "365d",
  73.             "status": "0",
  74.             "value_type": "3",
  75.             "trapper_hosts": "",
  76.             "units": "",
  77.             "formula": "",
  78.             "error": "",
  79.             "logtimefmt": "",
  80.             "templateid": "0",
  81.             "valuemapid": "0",
  82.             "params": "",
  83.             "ipmi_sensor": "",
  84.             "authtype": "0",
  85.             "username": "",
  86.             "password": "",
  87.             "publickey": "",
  88.             "privatekey": "",
  89.             "flags": "0",
  90.             "interfaceid": "0",
  91.             "description": "",
  92.             "inventory_link": "0",
  93.             "lifetime": "30d",
  94.             "state": "0",
  95.             "evaltype": "0",
  96.             "master_itemid": "25545",
  97.             "jmx_endpoint": "",
  98.             "timeout": "3s",
  99.             "url": "",
  100.             "query_fields": [],
  101.             "posts": "",
  102.             "status_codes": "200",
  103.             "follow_redirects": "1",
  104.             "post_type": "0",
  105.             "http_proxy": "",
  106.             "headers": [],
  107.             "retrieve_mode": "0",
  108.             "request_method": "0",
  109.             "output_format": "0",
  110.             "ssl_cert_file": "",
  111.             "ssl_key_file": "",
  112.             "ssl_key_password": "",
  113.             "verify_peer": "0",
  114.             "verify_host": "0",
  115.             "allow_traps": "0",
  116.             "lastclock": "0",
  117.             "lastns": "0",
  118.             "lastvalue": "0",
  119.             "prevvalue": "0",
  120.             "parameters": []
  121.         }
  122.     ],
  123.     "id": 1
  124. }

Find HTTP agent item

Find HTTP agent item with post body type XML for specific host id.

Request:

  1. {
  2.     "jsonrpc": "2.0",
  3.     "method": "item.get",
  4.     "params": {
  5.         "hostids": "10255",
  6.         "filter": {
  7.             "type": "19",
  8.             "post_type": "3"
  9.         }
  10.     },
  11.     "id": 3,
  12.     "auth": "d678e0b85688ce578ff061bd29a20d3b"
  13. }

Response:

  1. {
  2.     "jsonrpc": "2.0",
  3.     "result": [
  4.         {
  5.             "itemid": "28252",
  6.             "type": "19",
  7.             "snmp_oid": "",
  8.             "hostid": "10255",
  9.             "name": "template item",
  10.             "key_": "ti",
  11.             "delay": "30s",
  12.             "history": "90d",
  13.             "trends": "365d",
  14.             "status": "0",
  15.             "value_type": "3",
  16.             "trapper_hosts": "",
  17.             "units": "",
  18.             "formula": "",
  19.             "error": "",
  20.             "logtimefmt": "",
  21.             "templateid": "0",
  22.             "valuemapid": "0",
  23.             "params": "",
  24.             "ipmi_sensor": "",
  25.             "authtype": "0",
  26.             "username": "",
  27.             "password": "",
  28.             "publickey": "",
  29.             "privatekey": "",
  30.             "flags": "0",
  31.             "interfaceid": "0",
  32.             "description": "",
  33.             "inventory_link": "0",
  34.             "lifetime": "30d",
  35.             "state": "0",
  36.             "evaltype": "0",
  37.             "jmx_endpoint": "",
  38.             "master_itemid": "0",
  39.             "timeout": "3s",
  40.             "url": "localhost",
  41.             "query_fields": [
  42.                 {
  43.                     "mode": "xml"
  44.                 }
  45.             ],
  46.             "posts": "<body>\r\n<![CDATA[{$MACRO}<foo></bar>]]>\r\n</body>",
  47.             "status_codes": "200",
  48.             "follow_redirects": "0",
  49.             "post_type": "3",
  50.             "http_proxy": "",
  51.             "headers": [],
  52.             "retrieve_mode": "1",
  53.             "request_method": "3",
  54.             "output_format": "0",
  55.             "ssl_cert_file": "",
  56.             "ssl_key_file": "",
  57.             "ssl_key_password": "",
  58.             "verify_peer": "0",
  59.             "verify_host": "0",
  60.             "allow_traps": "0",
  61.             "lastclock": "0",
  62.             "lastns": "0",
  63.             "lastvalue": "0",
  64.             "prevvalue": "0",
  65.             "parameters": []
  66.         }
  67.     ],
  68.     "id": 3
  69. }

Retrieving items with preprocessing rules

Reatrieve all items and their preprocessing rules from host with ID “10254”.

Request:

  1. {
  2.     "jsonrpc": "2.0",
  3.     "method": "item.get",
  4.     "params": {
  5.         "output": ["itemid", "name", "key_"],
  6.         "selectPreprocessing": "extend",
  7.         "hostids": "10254"
  8.     },
  9.     "auth": "038e1d7b1735c6a5436ee9eae095879e",
  10.     "id": 1
  11. }

Response:

  1. {
  2.     "jsonrpc": "2.0",
  3.     "result": {
  4.         "itemid": "23865",
  5.         "name": "http agent example JSON",
  6.         "key_": "json",
  7.         "preprocessing": [
  8.             {
  9.                 "type": "12",
  10.                 "params": "$.random",
  11.                 "error_handler": "1",
  12.                 "error_handler_params": ""
  13.             }
  14.         ]
  15.     },
  16.     "id": 1
  17. }

See also

Source

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