Table of Contents
Item object
The following objects are directly related to the item API.
Item
Web items cannot be directly created, updated or deleted via the Zabbix API.
The item object has the following properties.
| Property | Type | Description |
|---|---|---|
| itemid | ID | ID of the item. Property behavior: - read-only - required for update operations |
| delay | string | Update interval of the item. Accepts seconds or time unit with suffix (e.g., 30s, 1m, 2h, 1d) and, optionally, one or more custom intervals, all separated by semicolons. Custom intervals can be a mix of flexible and scheduling intervals. Accepts user macros. If used, the value must be a single macro. Multiple macros or macros mixed with text are not supported. Flexible intervals may be written as two macros separated by a forward slash (e.g., {$FLEX_INTERVAL}/{$FLEX_PERIOD}).Example: 1h;wd1-5h9-18;{$Macro1}/1-7,00:00-24:00;0/6-7,12:00-24:00;{$Macro2}/{$Macro3}Property behavior: - required if type is set to "Zabbix agent" (0), "Simple check" (3), "Zabbix internal" (5), "External check" (10), "Database monitor" (11), "IPMI agent" (12), "SSH agent" (13), "TELNET agent" (14), "Calculated" (15), "JMX agent" (16), "HTTP agent" (19), "SNMP agent" (20), "Script" (21), "Browser" (22), or if type is set to "Zabbix agent (active)" (7) and key_ does not contain "mqtt.get" |
| hostid | ID | ID of the host or template that the item belongs to. Property behavior: - constant - required for create operations |
| interfaceid | ID | ID of the item's host interface. Property behavior: - required if item belongs to host and type is set to "Zabbix agent", "IPMI agent", "JMX agent", "SNMP trap", or "SNMP agent"- supported if item belongs to host and type is set to "Simple check", "External check", "SSH agent", "TELNET agent", or "HTTP agent"- read-only for discovered objects |
| key_ | string | Item key. Property behavior: - required for create operations - read-only for inherited objects or discovered objects |
| name | string | Name of the item. Supports user macros. Property behavior: - required for create operations - read-only for inherited objects or discovered objects |
| name_resolved | string | Name of the item with resolved user macros. Property behavior: - read-only |
| type | integer | Type of the item. Possible values: 0 - Zabbix agent; 2 - Zabbix trapper; 3 - Simple check; 5 - Zabbix internal; 7 - Zabbix agent (active); 9 - Web item; 10 - External check; 11 - Database monitor; 12 - IPMI agent; 13 - SSH agent; 14 - TELNET agent; 15 - Calculated; 16 - JMX agent; 17 - SNMP trap; 18 - Dependent item; 19 - HTTP agent; 20 - SNMP agent; 21 - Script; 22 - Browser. Property behavior: - required for create operations - read-only for inherited objects or discovered objects |
| url | string | URL string. Supports user macros, {HOST.IP}, {HOST.CONN}, {HOST.DNS}, {HOST.HOST}, {HOST.NAME}, {HOST.PORT}, {ITEM.ID}, {ITEM.KEY}. Property behavior: - required if type is set to "HTTP agent"- read-only for inherited objects or discovered objects |
| value_type | integer | Type of information of the item. Possible values: 0 - numeric float; 1 - character; 2 - log; 3 - numeric unsigned; 4 - text; 5 - binary. Property behavior: - required for create operations - read-only for inherited objects or discovered objects |
| allow_traps | integer | Allow to populate value similarly to the trapper item. 0 - (default) Do not allow to accept incoming data; 1 - Allow to accept incoming data. Property behavior: - supported if type is set to "HTTP agent"- read-only for discovered objects |
| authtype | integer | Authentication method. Possible values if type is set to "SSH agent":0 - (default) password; 1 - public key. Possible values if type is set to "HTTP agent":0 - (default) none; 1 - basic; 2 - NTLM; 3 - Kerberos. Property behavior: - supported if type is set to "SSH agent" or "HTTP agent"- read-only for inherited objects (if type is set to "HTTP agent") or discovered objects |
| description | string | Description of the item. Property behavior: - read-only for discovered objects |
| error | string | Error text if there are problems updating the item value. Property behavior: - read-only |
| flags | integer | Origin of the item. Possible values: 0 - a plain item; 4 - a discovered item. Property behavior: - read-only |
| follow_redirects | integer | Follow response redirects while polling data. Possible values: 0 - Do not follow redirects; 1 - (default) Follow redirects. Property behavior: - supported if type is set to "HTTP agent"- read-only for inherited objects or discovered objects |
| headers | array | Array of headers that will be sent when performing an HTTP request. Property behavior: - supported if type is set to "HTTP agent"- read-only for inherited objects or discovered objects |
| history | string | A time unit of how long the history data should be stored. Also accepts user macro. Default: 31d. Property behavior: - read-only for discovered objects |
| http_proxy | string | HTTP(S) proxy connection string. Property behavior: - supported if type is set to "HTTP agent"- read-only for inherited objects or discovered objects |
| inventory_link | integer | ID of the host inventory field that is populated by the item. Refer to the host inventory page for a list of supported host inventory fields and their IDs. Default: 0. Property behavior: - supported if value_type is set to "numeric float", "character", "numeric unsigned", or "text"- read-only for discovered objects |
| ipmi_sensor | string | IPMI sensor. Property behavior: - required if type is set to "IPMI agent" and key_ is not set to "ipmi.get"- supported if type is set to "IPMI agent"- read-only for inherited objects or discovered objects |
| jmx_endpoint | string | JMX agent custom connection string. Default value: service:jmx:rmi:///jndi/rmi://{HOST.CONN}:{HOST.PORT}/jmxrmi Property behavior: - supported if type is set to "JMX agent"- read-only for discovered objects |
| lastclock | timestamp | Time when the item value was last updated. By default, only values that fall within the last 24 hours are displayed. You can extend this time period by changing the value of Max history display period parameter in the Administration → General menu section. Property behavior: - read-only |
| lastns | integer | Nanoseconds when the item value was last updated. By default, only values that fall within the last 24 hours are displayed. You can extend this time period by changing the value of Max history display period parameter in the Administration → General menu section. Property behavior: - read-only |
| lastvalue | string | Last value of the item. By default, only values that fall within the last 24 hours are displayed. You can extend this time period by changing the value of Max history display period parameter in the Administration → General menu section. Property behavior: - read-only |
| logtimefmt | string | Format of the time in log entries. Property behavior: - supported if value_type is set to "log"- read-only for inherited objects or discovered objects |
| master_itemid | ID | ID of the master item. Recursion up to 3 dependent items and maximum count of dependent items equal to 29999 are allowed. Property behavior: - required if type is set to "Dependent item"- read-only for inherited objects or discovered objects |
| output_format | integer | Should the response be converted to JSON. 0 - (default) Store raw; 1 - Convert to JSON. Property behavior: - supported if type is set to "HTTP agent"- read-only for inherited objects or discovered objects |
| params | string | Additional parameters depending on the type of the item: - executed script for SSH agent and TELNET agent items; - SQL query for database monitor items; - formula for calculated items; - the script for script and browser items. Property behavior: - required if type is set to "Database monitor", "SSH agent", "TELNET agent", "Calculated", "Script", or "Browser"- read-only for inherited objects (if type is set to "Script" or "Browser") or discovered objects |
| parameters | object/array | Additional parameters if type is set to "Script" or "Browser". Array of objects with name and value properties, where name must be unique.Property behavior: - supported if type is set to "Script" or "Browser"- read-only for inherited objects or discovered objects |
| password | string | Password for authentication. Property behavior: - required if type is set to "JMX agent" and username is set- supported if type is set to "Simple check", "SSH agent", "TELNET agent", "Database monitor", or "HTTP agent"- read-only for inherited objects (if type is set to "HTTP agent") or discovered objects |
| post_type | integer | Type of post data body stored in posts property.Possible values: 0 - (default) Raw data; 2 - JSON data; 3 - XML data. Property behavior: - supported if type is set to "HTTP agent"- read-only for inherited objects or discovered objects |
| posts | string | HTTP(S) request body data. Property behavior: - required if type is set to "HTTP agent" and post_type is set to "JSON data" or "XML data"- supported if type is set to "HTTP agent" and post_type is set to "Raw data"- read-only for inherited objects or discovered objects |
| prevvalue | string | Previous value of the item. By default, only values that fall within the last 24 hours are displayed. You can extend this time period by changing the value of Max history display period parameter in the Administration → General menu section. Property behavior: - read-only |
| privatekey | string | Name of the private key file. Property behavior: - required if type is set to "SSH agent" and authtype is set to "public key"- read-only for discovered objects |
| publickey | string | Name of the public key file. Property behavior: - required if type is set to "SSH agent" and authtype is set to "public key"- read-only for discovered objects |
| query_fields | array | Array of query fields that will be sent when performing an HTTP request. Property behavior: - supported if type is set to "HTTP agent"- read-only for inherited objects or discovered objects |
| request_method | integer | Type of request method. Possible values: 0 - (default) GET; 1 - POST; 2 - PUT; 3 - HEAD. Property behavior: - supported if type is set to "HTTP agent"- read-only for inherited objects or discovered objects |
| retrieve_mode | integer | What part of response should be stored. Possible values if request_method is set to "GET", "POST", or "PUT":0 - (default) Body; 1 - Headers; 2 - Both body and headers will be stored. Possible values if request_method is set to "HEAD":1 - Headers. Property behavior: - supported if type is set to "HTTP agent"- read-only for inherited objects or discovered objects |
| snmp_oid | string | SNMP OID. Property behavior: - required if type is set to "SNMP agent"- read-only for inherited objects or discovered objects |
| ssl_cert_file | string | Public SSL Key file path. Property behavior: - supported if type is set to "HTTP agent"- read-only for inherited objects or discovered objects |
| ssl_key_file | string | Private SSL Key file path. Property behavior: - supported if type is set to "HTTP agent"- read-only for inherited objects or discovered objects |
| ssl_key_password | string | Password for SSL Key file. Property behavior: - supported if type is set to "HTTP agent"- read-only for inherited objects or discovered objects |
| state | integer | State of the item. Possible values: 0 - (default) normal; 1 - not supported. Property behavior: - read-only |
| status | integer | Status of the item. Possible values: 0 - (default) enabled item; 1 - disabled item. |
| status_codes | string | Ranges of required HTTP status codes, separated by commas. Also supports user macros as part of comma separated list. Example: 200,200-{$M},{$M},200-400 Property behavior: - supported if type is set to "HTTP agent"- read-only for inherited objects or discovered objects |
| templateid | ID | ID of the parent template item. Hint: Use the hostid property to specify the template that the item belongs to.Property behavior: - read-only |
| timeout | string | Item data polling request timeout. Accepts seconds or time unit with suffix (e.g., 30s, 1m). Also accepts user macros. Possible values range: 1-600s. Default: "" - use proxy/global settings. Property behavior: - supported if type is set to "Zabbix agent" (0), "Simple check" (3) and key_ does not start with "vmware." and "icmpping", "Zabbix agent (active)" (7), "External check" (10), "Database monitor" (11), "SSH agent" (13), "TELNET agent" (14), "HTTP agent" (19), "SNMP agent" (20) and snmp_oid starts with "walk[" or "get[", "Script" (21), "Browser" (22)- read-only for inherited and discovered objects |
| trapper_hosts | string | Allowed hosts. Property behavior: - readonly for discovered objects - supported if type is set to "Zabbix trapper", or if type is set to "HTTP agent" and allow_traps is set to "Allow to accept incoming data" |
| trends | string | A time unit of how long the trends data should be stored. Also accepts user macro. Default: 365d. Property behavior: - supported if value_type is set to "numeric float" or "numeric unsigned"- read-only for discovered objects |
| units | string | Value units. Property behavior: - supported if value_type is set to "numeric float" or "numeric unsigned"- read-only for inherited objects or discovered objects |
| username | string | Username for authentication. Property behavior: - required if type is set to "SSH agent", "TELNET agent", or if type is set to "JMX agent" and password is set- supported if type is set to "Simple check", "Database monitor", or "HTTP agent"- read-only for inherited objects (if type is set to "HTTP agent") or discovered objects |
| uuid | string | Universal unique identifier, used for linking imported item to already existing ones. Auto-generated, if not given. Property behavior: - supported if the item belongs to a template |
| valuemapid | ID | ID of the associated value map. Property behavior: - supported if value_type is set to "numeric float", "character", or "numeric unsigned"- read-only for inherited objects or discovered objects |
| verify_host | integer | Whether to validate that the host name for the connection matches the one in the host's certificate. Possible values: 0 - (default) Do not validate; 1 - Validate. Property behavior: - supported if type is set to "HTTP agent"- read-only for inherited objects or discovered objects |
| verify_peer | integer | Whether to validate that the host's certificate is authentic. Possible values: 0 - (default) Do not validate; 1 - Validate. Property behavior: - supported if type is set to "HTTP agent"- read-only for inherited objects or discovered objects |
HTTP header
The header object has the following properties:
| Property | Type | Description |
|---|---|---|
| name | string | HTTP header name. Property behavior: - required |
| value | string | Header value. Property behavior: - required |
HTTP query field
The query field object defines a name and value that is used to specify a URL parameter. It has the following properties:
| Property | Type | Description |
|---|---|---|
| name | string | Name of the parameter. Property behavior: - required |
| value | string | Parameter value. Property behavior: - required |
Item tag
The item tag object has the following properties.
| Property | Type | Description |
|---|---|---|
| tag | string | Item tag name. Property behavior: - required |
| value | string | Item tag value. |
Item preprocessing
The item preprocessing object has the following properties.
| Property | Type | Description |
|---|---|---|
| type | integer | The preprocessing option type. Possible values: 1 - Custom multiplier; 2 - Right trim; 3 - Left trim; 4 - Trim; 5 - Regular expression; 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; 26 - Check unsupported; 27 - XML to JSON; 28 - SNMP walk value; 29 - SNMP walk to JSON; 30 - SNMP get value. Property behavior: - required |
| params | string | Additional parameters used by preprocessing option. Multiple parameters are separated by the newline (\n) character. If type is set to "Check unsupported", the parameters follow a <scope>[\n<pattern>] syntax, where pattern is a regular expression, and scope is one of:-1 - match any error; 0 - check if error message matches pattern; 1 - check if error message does not match pattern. Property behavior: - required if type is set to "Custom multiplier" (1), "Right trim" (2), "Left trim" (3), "Trim" (4), "Regular expression" (5), "XML XPath" (11), "JSONPath" (12), "In range" (13), "Matches regular expression" (14), "Does not match regular expression" (15), "Check for error in JSON" (16), "Check for error in XML" (17), "Check for error using regular expression" (18), "Discard unchanged with heartbeat" (20), "JavaScript" (21), "Prometheus pattern" (22), "Prometheus to JSON" (23), "CSV to JSON" (24), "Replace" (25), Check unsupported (26), "SNMP walk value" (28), "SNMP walk to JSON" (29), or "SNMP get value" (30) |
| error_handler | integer | Action type used in case of preprocessing step failure. Possible values: 0 - Error message is set by Zabbix server; 1 - Discard value; 2 - Set custom value; 3 - Set custom error message. Possible values if type is set to "Check unsupported":1 - Discard value; 2 - Set custom value; 3 - Set custom error message. Property behavior: - required if type is set to "Custom multiplier" (1), "Regular expression" (5), "Boolean to decimal" (6), "Octal to decimal" (7), "Hexadecimal to decimal" (8), "Simple change" (9), "Change per second" (10), "XML XPath" (11), "JSONPath" (12), "In range" (13), "Matches regular expression" (14), "Does not match regular expression" (15), "Check for error in JSON" (16), "Check for error in XML" (17), "Check for error using regular expression" (18), "Prometheus pattern" (22), "Prometheus to JSON" (23), "CSV to JSON" (24), "Check unsupported" (26), "XML to JSON" (27), "SNMP walk value" (28), "SNMP walk to JSON" (29), or "SNMP get value" (30) |
| error_handler_params | string | Error handler parameters. Property behavior: - required if error_handler is set to "Set custom value" or "Set custom error message" |
The following parameters and error handlers are supported for each preprocessing type.
| Preprocessing type | Name | Parameter 1 | Parameter 2 | Parameter 3 | Supported error handlers |
|---|---|---|---|---|---|
| 1 | Custom multiplier | number1, 6 | 0, 1, 2, 3 | ||
| 2 | Right trim | list of characters2 | |||
| 3 | Left trim | list of characters2 | |||
| 4 | Trim | list of characters2 | |||
| 5 | Regular expression | pattern3 | output2 | 0, 1, 2, 3 | |
| 6 | Boolean to decimal | 0, 1, 2, 3 | |||
| 7 | Octal to decimal | 0, 1, 2, 3 | |||
| 8 | Hexadecimal to decimal | 0, 1, 2, 3 | |||
| 9 | Simple change | 0, 1, 2, 3 | |||
| 10 | Change per second | 0, 1, 2, 3 | |||
| 11 | XML XPath | path4 | 0, 1, 2, 3 | ||
| 12 | JSONPath | path4 | 0, 1, 2, 3 | ||
| 13 | In range | min1, 6 | max1, 6 | 0, 1, 2, 3 | |
| 14 | Matches regular expression | pattern3 | 0, 1, 2, 3 | ||
| 15 | Does not match regular expression | pattern3 | 0, 1, 2, 3 | ||
| 16 | Check for error in JSON | path4 | 0, 1, 2, 3 | ||
| 17 | Check for error in XML | path4 | 0, 1, 2, 3 | ||
| 18 | Check for error using regular expression | pattern3 | output2 | 0, 1, 2, 3 | |
| 19 | Discard unchanged | ||||
| 20 | Discard unchanged with heartbeat | seconds5, 6 | |||
| 21 | JavaScript | script2 | |||
| 22 | Prometheus pattern | pattern6, 7 | value, label, function |
output8, 9 | 0, 1, 2, 3 |
| 23 | Prometheus to JSON | pattern6, 7 | 0, 1, 2, 3 | ||
| 24 | CSV to JSON | character2 | character2 | 0,1 | 0, 1, 2, 3 |
| 25 | Replace | search string2 | replacement2 | ||
| 26 | Check unsupported | scope1 | pattern3, 6 | 1, 2, 3 | |
| 27 | XML to JSON | 0, 1, 2, 3 | |||
| 28 | SNMP walk value | OID2 | Format: 0 - Unchanged 1 - UTF-8 from Hex-STRING 2 - MAC from Hex-STRING 3 - Integer from BITS |
0, 1, 2, 3 | |
| 29 | SNMP walk to JSON10 | Field name2 | OID prefix2 | Format: 0 - Unchanged 1 - UTF-8 from Hex-STRING 2 - MAC from Hex-STRING 3 - Integer from BITS |
0, 1, 2, 3 |
| 30 | SNMP get value | Format: 1 - UTF-8 from Hex-STRING 2 - MAC from Hex-STRING 3 - Integer from BITS |
0, 1, 2, 3 | ||
1 integer or floating-point number
2 string
3 regular expression
4 JSONPath or XML XPath
5 positive integer (with support of time suffixes, e.g. 30s, 1m, 2h, 1d)
6 user macro
7 Prometheus pattern following the syntax: <metric name>{<label name>="<label value>", ...} == <value>. Each Prometheus pattern component (metric, label name, label value and metric value) can be user macro.
8 Prometheus output following the syntax: <label name> (can be a user macro) if label is selected as the second parameter.
9 One of the aggregation functions: sum, min, max, avg, count if function is selected as the second parameter.
10 Supports multiple "Field name,OID prefix,Format records" records delimited by a new line character.