item_threshold_search
Finds Zabbix items whose current values exceed or fall below numeric thresholds, enabling quick checks of utilization, capacity, and counters without manual post-processing.
Instructions
Find items whose current lastvalue is above or below a numeric threshold.
Fetches all items matching the query via item.get, filters client-side by lastvalue, and returns sorted results. Non-numeric lastvalues are skipped. Replaces manual item_get + float(lastvalue) post-processing.
Typical uses:
SNAT pool utilization above 50%: search={"key_": ".usage"}, lastvalue_ge=50
Interface discard counter above 0: search={"key_": "discards"}, lastvalue_gt=0
Disk usage near capacity: search={"key_": "pused"}, lastvalue_ge=80
Which key carries a metric depends on the templates in use (memory may be 'vm.memory.utilization', 'vm.memory.size[pused]' or 'vm.memory.size[pavailable]'; a disk has one 'vfs.fs.size[,pused]' item per filesystem). A key fragment must come from the items that exist: when it is not known, look first with item_get (search on name or key_, output itemid, name, key_, units, value_type) and use the key_ it returns. The threshold is compared with lastvalue as stored, so check 'units' (a percentage versus bytes).
Returns {"scanned": N, "matched": M, "returned": R, "items": [...]} sorted by lastvalue. matched = total passing threshold; returned = items included (may be less if result_limit set).
Input Schema
| Name | Required | Description | Default |
|---|---|---|---|
| filter | No | Exact-match filter, e.g. {"type": 0} for Zabbix agent items. Return only results whose properties exactly match the given values (a single value or a list of values per key). Example: {"status": 0} or {"status": [0, 1]}. Keys: allow_traps, authtype, delay, enabled_lifetime (7.0+), enabled_lifetime_type (7.0+), evaltype, flags, follow_redirects, formula, granularity (8.0+), history, hostid, http_proxy, interfaceid, inventory_link, ipmi_sensor, itemid, jmx_endpoint, key_, lifetime, lifetime_type (7.0+), logtimefmt, lookback_limit (8.0+), master_itemid, name, name_resolved (7.0+), output_format, password, post_type, privatekey, publickey, request_method, retrieve_mode, snmp_oid, ssl_cert_file, ssl_key_file, ssl_key_password, state, status, status_codes, templateid, time_shift (8.0+), timeout, trapper_hosts, trends, type, units, url, username, uuid (6.0+), value_type, valuemapid, verify_host, verify_peer. Text properties cannot be filtered; use 'search' for them. | |
| output | No | Item properties to return: a list of names, or 'extend'. Default: itemid, name, key_, lastvalue; lastvalue is always included for the threshold. Properties: allow_traps, authtype, delay, description, enabled_lifetime (7.0+), enabled_lifetime_type (7.0+), error, evaltype, flags, follow_redirects, formula, granularity (8.0+), headers, history, hostid, http_proxy, interfaceid, inventory_link, ipmi_sensor, itemid, jmx_endpoint, key_, lastclock, lastns, lastvalue, lifetime, lifetime_type (7.0+), logtimefmt, lookback_limit (8.0+), master_itemid, name, name_resolved (7.0+), output_format, parameters (6.0+), params, password, post_type, posts, prevvalue, privatekey, publickey, query (8.0+), query_fields, request_method, retrieve_mode, snmp_oid, ssl_cert_file, ssl_key_file, ssl_key_password, state, status, status_codes, templateid, time_shift (8.0+), timeout, trapper_hosts, trends, type, units, url, username, uuid (6.0+), value_type, valuemapid, verify_host, verify_peer. | |
| search | No | Substring search, e.g. {"key_": "discards"} or {"key_": ".usage"} ('discards' matches 'net.if.in.discards[eth0]'). Return results whose string properties contain the given pattern (case-insensitive; '*' is a wildcard when searchWildcardsEnabled is true). Example: {"name": "web"}. Keys: delay, description, error, formula, granularity (8.0+), history, http_proxy, ipmi_sensor, jmx_endpoint, key_, lifetime, logtimefmt, lookback_limit (8.0+), name, name_resolved (7.0+), params, password, posts, privatekey, publickey, snmp_oid, ssl_cert_file, ssl_key_file, ssl_key_password, status_codes, time_shift (8.0+), timeout, trapper_hosts, trends, units, url, username, uuid (6.0+). | |
| server | No | Target Zabbix server. Available: default. Defaults to 'default' if omitted. | |
| hostids | No | Restrict search to these host IDs (from host_get) | |
| groupids | No | Restrict search to these host group IDs (from hostgroup_get) | |
| raw_json | No | Strips the security disclaimer preamble from the response so it is pure JSON. Default: false. Requires the bearer token to have 'allow_raw_json' explicitly enabled by an operator in the admin portal - tokens without that policy receive a PolicyError instead. WARNING: setting true bypasses the prompt-injection mitigation marker that wraps untrusted Zabbix data (host names, item descriptions, problem text). LLM clients (Claude, GPT, Cursor, ...) should leave this false; only programmatic non-LLM consumers (Python scripts, n8n workflows that json.loads the result) should set true. | |
| sort_desc | No | Sort matched items by lastvalue descending — highest values first (default: true) | |
| extra_params | No | Additional item.get parameters, e.g. {"selectHosts": ["host"]} for the host name or {"searchWildcardsEnabled": true} for wildcards. Other native item.get parameters, merged into the request as-is. Parameters: evaltype (6.0+), graphids, group, host, inherited, inheritedTags (8.0+), interfaceids, itemids, limitSelects, monitored, proxyids, tags (6.0+), templated, templateids, triggerids, webitems, with_triggers. Switches (true turns one on, false is the same as leaving it out): webitems. Sub-object selects (value 'extend', 'count' or a list of property names): selectDiscoveryData (7.4+), selectDiscoveryRule, selectGraphs, selectHosts, selectInheritedTags (8.0+), selectInterfaces, selectItemDiscovery (deprecated in 7.4, use selectDiscoveryData), selectPreprocessing, selectTags (6.0+), selectTriggers, selectValueMap (6.0+). Any other key is refused here, because Zabbix would silently ignore it. For a parameter you are sure exists on your release but is not listed, use zabbix_raw_api_call. | |
| lastvalue_ge | No | Keep only items where lastvalue >= this value (e.g. 50.0 to find SNAT pools above 50% utilization) | |
| lastvalue_gt | No | Keep only items where lastvalue > this value (strict greater-than) | |
| lastvalue_le | No | Keep only items where lastvalue <= this value | |
| lastvalue_lt | No | Keep only items where lastvalue < this value (strict less-than) | |
| result_limit | No | Max number of matched items to return after threshold filtering |