> Item object

> 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	string	ID of the item. Property behavior: - read-only - required for update operations
delay	string	Update interval of the item. Accepts seconds or a time unit with suffix (30s,1m,2h,1d). Optionally one or more custom intervals can be specified either as flexible intervals or scheduling. Multiple intervals are separated by a semicolon. User macros may be used. A single macro has to fill the whole field. Multiple macros in a field or macros mixed with text are not supported. Flexible intervals may be written as two macros separated by a forward slash (e.g. `{$FLEXINTERVAL}/{$FLEX_PERIOD}`). 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), or if `type` is set to “Zabbix agent (active)” (7) and `key` does not contain “mqtt.get”
hostid	string	ID of the host or template that the item belongs to. Property behavior: - constant - required for create operations
interfaceid	string	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. Property behavior: - required for create operations - read-only for inherited objects or discovered objects
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. 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}, {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. 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. 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 pooling 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	object	Object with HTTP(S) request headers, where header name is used as key and header value as value. Example: { “User-Agent”: “Zabbix” } 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: 90d. 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 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 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	integer	Master item ID. 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 item. Property behavior: - required if `type` is set to “Database monitor”, “SSH agent”, “TELNET agent”, “Calculated”, or “Script” - read-only for inherited objects (if `type` is set to “Script”) or discovered objects
parameters	array	Additional parameters if `type` is set to “Script”. Array of objects with `name` and `value` properties, where `name` must be unique. Property behavior: - supported if `type` is set to “Script” - 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	Query parameters. Array of objects with `key`:`value` pairs, where `value` can be an empty string. 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	string	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. Supports user macros. Default: `3s`. Maximum value: `60s`. Property behavior: - supported if `type` is set to “HTTP agent” or “Script” - read-only for inherited objects or 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	string	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	Validate host name in URL is in Common Name field or a Subject Alternate Name field of host 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	Validate is host certificate 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

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 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; 26 - Check unsupported; 27 - XML to JSON; 28 - SNMP walk value; 29 - SNMP walk to JSON. Property behavior: - required
params	string	Additional parameters used by preprocessing option. Multiple parameters are separated by the newline (\n) character. Property behavior: - required if `type` is set to “Custom multiplier” (1), “Right trim” (2), “Left trim” (3), “Trim” (4), “Regular expression matching” (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), “SNMP walk value” (28), or “SNMP walk to JSON” (29)
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 matching” (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), or “SNMP walk to JSON” (29)
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	number^1, 6			0, 1, 2, 3
2	Right trim	list of characters²
3	Left trim	list of characters²
4	Trim	list of characters²
5	Regular expression	pattern³	output²		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	path⁴			0, 1, 2, 3
12	JSONPath	path⁴			0, 1, 2, 3
13	In range	min^1, 6	max^1, 6		0, 1, 2, 3
14	Matches regular expression	pattern³			0, 1, 2, 3
15	Does not match regular expression	pattern³			0, 1, 2, 3
16	Check for error in JSON	path⁴			0, 1, 2, 3
17	Check for error in XML	path⁴			0, 1, 2, 3
18	Check for error using regular expression	pattern³	output²		0, 1, 2, 3
19	Discard unchanged
20	Discard unchanged with heartbeat	seconds^5, 6
21	JavaScript	script²
22	Prometheus pattern	pattern^6, 7	`value`, `label`, `function`	output^8, 9	0, 1, 2, 3
23	Prometheus to JSON	pattern^6, 7			0, 1, 2, 3
24	CSV to JSON	character²	character²	0,1	0, 1, 2, 3
25	Replace	search string²	replacement²
26	Check unsupported				1, 2, 3
27	XML to JSON				0, 1, 2, 3
28	SNMP walk value	OID²	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 JSON¹⁰	Field name²	OID prefix²	Format: 0 - Unchanged 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.