Table of Contents
host.get
Description
integer/array host.get(object parameters)
The method allows to retrieve hosts 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.
| Parameter | Type | Description |
|---|---|---|
| groupids | ID/array | Return only hosts that belong to the given groups. |
| dserviceids | ID/array | Return only hosts that are related to the given discovered services. |
| graphids | ID/array | Return only hosts that have the given graphs. |
| hostids | ID/array | Return only hosts with the given host IDs. |
| httptestids | ID/array | Return only hosts that have the given web checks. |
| interfaceids | ID/array | Return only hosts that use the given interfaces. |
| itemids | ID/array | Return only hosts that have the given items. |
| maintenanceids | ID/array | Return only hosts that are affected by the given maintenances. |
| monitored_hosts | flag | Return only monitored hosts. |
| proxyids | ID/array | Return only hosts that are monitored by the given proxies. |
| proxy_groupids | ID/array | Return only hosts that are monitored by the given proxy groups. |
| templated_hosts | flag | Return both hosts and templates. |
| templateids | ID/array | Return only hosts that are linked to the given templates. |
| triggerids | ID/array | Return only hosts that have the given triggers. |
| with_items | flag | Return only hosts that have items. Overrides the with_monitored_items and with_simple_graph_items parameters. |
| with_item_prototypes | flag | Return only hosts that have item prototypes. Overrides the with_simple_graph_item_prototypes parameter. |
| with_simple_graph_item_prototypes | flag | Return only hosts that have item prototypes, which are enabled for creation and have numeric type of information. |
| with_graphs | flag | Return only hosts that have graphs. |
| with_graph_prototypes | flag | Return only hosts that have graph prototypes. |
| with_httptests | flag | Return only hosts that have web checks. Overrides the with_monitored_httptests parameter. |
| with_monitored_httptests | flag | Return only hosts that have enabled web checks. |
| with_monitored_items | flag | Return only hosts that have enabled items. Overrides the with_simple_graph_items parameter. |
| with_monitored_triggers | flag | Return only hosts that have enabled triggers. All of the items used in the trigger must also be enabled. |
| with_simple_graph_items | flag | Return only hosts that have items with numeric type of information. |
| with_triggers | flag | Return only hosts that have triggers. Overrides the with_monitored_triggers parameter. |
| withProblemsSuppressed | boolean | Return hosts that have suppressed problems. Possible values: null - (default) all hosts;true - only hosts with suppressed problems;false - only hosts with unsuppressed problems. |
| evaltype | integer | Rules for tag searching. Possible values: 0 - (default) And/Or; 2 - Or. |
| severities | integer/array | Return hosts that have only problems with given severities. Applies only if problem object is trigger. |
| tags | object/array | Return only hosts with given tags. Exact match by tag and case-sensitive or case-insensitive search by tag value depending on operator value. Format: [{"tag": "<tag>", "value": "<value>", "operator": "<operator>"}, ...].An empty array returns all hosts. Possible operator values: 0 - (default) Contains (substring match, case-insensitive); 1 - Equals (case-sensitive); 2 - Does not contain (substring match, case-insensitive); 3 - Does not equal (case-sensitive); 4 - Exists; 5 - Does not exist. |
| inheritedTags | boolean | Return hosts that have given tags also in all of their linked templates. Default:Possible values: true - linked templates must also have given tags;false - (default) linked template tags are ignored. |
| selectDiscoveryData | query | Return a discoveryData property with the host discovery object data. The host discovery object links a discovered host to a host prototype from which it was discovered.It has the following properties: host - (string) ID of the host;parent_hostid - (string) ID of the host prototype from which the host has been created;status - (int) host discovery status:0 - (default) host is discovered, 1 - host is not discovered anymore; ts_delete - (timestamp) time when a host that is no longer discovered will be deleted;ts_disable - (timestamp) time when a host that is no longer discovered will be disabled;disable_source - (int) indicator of whether host was disabled by an LLD rule or manually:0 - (default) disabled automatically, 1 - disabled by an LLD rule. |
| selectDiscoveryRule | query | Return a discoveryRule property with the low-level discovery rule that created the host (from host prototype in VMware monitoring). |
| selectDiscoveryRules | query | Return a discoveryRules property with host LLD rules. Supports count. |
| selectGraphs | query | Return a graphs property with host graphs.Supports count. |
| selectHostGroups | query | Return a hostgroups property with host groups data that the host belongs to. |
| selectHttpTests | query | Return an httpTests property with host web scenarios.Supports count. |
| selectInterfaces | query | Return an interfaces property with host interfaces.Supports count. |
| selectInventory | query | Return an inventory property with host inventory data. |
| selectItems | query | Return an items property with host items.Supports count. |
| selectMacros | query | Return a macros property with host macros. |
| selectParentTemplates | query | Return a parentTemplates property with templates that the host is linked to.In addition to Template object fields, it contains link_type - (integer) the way that the template is linked to host.Possible values: 0 - (default) manually linked; 1 - automatically linked by LLD. Supports count. |
| selectDashboards | query | Return a dashboards property.Supports count. |
| selectTags | query | Return a tags property with host tags. |
| selectInheritedTags | query | Return an inheritedTags property with tags that are on all templates which are linked to host. |
| selectTriggers | query | Return a triggers property with host triggers.Supports count. |
| selectValueMaps | query | Return a valuemaps property with host value maps. |
| filter | object | Return only those results that exactly match the given filter. Accepts an object, where the keys are property names, and the values are either a single value or an array of values to match against. Does not support properties of text data type.Supports additional properties: Host interface properties. |
| limitSelects | integer | Limits the number of records returned by subselects. Applies to the following subselects: selectParentTemplates - results will be sorted by host;selectInterfaces;selectItems - sorted by name;selectDiscoveryRules - sorted by name;selectTriggers - sorted by description;selectGraphs - sorted by name;selectDashboards - sorted by name. |
| search | object | Return results that match the given pattern (case-insensitive). Accepts an object, where the keys are property names, and the values are strings to search for. If no additional options are given, this will perform a LIKE "%…%" search.Supports only properties of string and text data type.Supports additional properties: Host interface properties. |
| searchInventory | object | Return hosts that have inventory data that match the given pattern (case-insensitive). Accepts an object, where the keys are property names, and the values are strings to search for. If no additional options are given, this will perform a LIKE "%…%" search.Supports only properties of string and text data type. |
| sortfield | string/array | Sort the result by the given properties. Possible values: hostid, host, name, status. |
| countOutput | boolean | These parameters are described in the reference commentary. |
| editable | boolean | |
| excludeSearch | boolean | |
| limit | integer | |
| output | query | |
| preservekeys | boolean | |
| searchByAny | boolean | |
| searchWildcardsEnabled | boolean | |
| sortorder | string/array | |
| startSearch | boolean | |
| selectDiscoveries | query | Return a discoveries property with host low-level discovery rules.Supports count.This query is deprecated, please use selectDiscoveryRules instead. |
| selectHostDiscovery | query | Return a hostDiscovery property with host discovery object data.This query is deprecated, please use selectDiscoveryData instead. |
Return values
(integer/array) Returns either:
- an array of objects;
- the count of retrieved objects, if the
countOutputparameter has been used.
Examples
Retrieving data by name
Retrieve all data about two hosts named "Zabbix server" and "Linux server".
{
"jsonrpc": "2.0",
"method": "host.get",
"params": {
"filter": {
"host": [
"Zabbix server",
"Linux server"
]
}
},
"id": 1
}Response:
{
"jsonrpc": "2.0",
"result": [
{
"hostid": "10160",
"proxyid": "0",
"host": "Zabbix server",
"status": "0",
"ipmi_authtype": "-1",
"ipmi_privilege": "2",
"ipmi_username": "",
"ipmi_password": "",
"maintenanceid": "0",
"maintenance_status": "0",
"maintenance_type": "0",
"maintenance_from": "0",
"name": "Zabbix server",
"flags": "0",
"description": "The Zabbix monitoring server.",
"tls_connect": "1",
"tls_accept": "1",
"tls_issuer": "",
"tls_subject": "",
"proxy_groupid": "0",
"monitored_by": "0",
"inventory_mode": "1",
"active_available": "1",
"assigned_proxyid": "0"
},
{
"hostid": "10167",
"proxyid": "0",
"host": "Linux server",
"status": "0",
"ipmi_authtype": "-1",
"ipmi_privilege": "2",
"ipmi_username": "",
"ipmi_password": "",
"maintenanceid": "0",
"maintenance_status": "0",
"maintenance_type": "0",
"maintenance_from": "0",
"name": "Linux server",
"flags": "0",
"description": "",
"tls_connect": "1",
"tls_accept": "1",
"tls_issuer": "",
"tls_subject": "",
"proxy_groupid": "0",
"monitored_by": "0",
"inventory_mode": "1",
"active_available": "1",
"assigned_proxyid": "0"
}
],
"id": 1
}Retrieving host groups
Retrieve host groups that the host "Zabbix server" is a member of.
{
"jsonrpc": "2.0",
"method": "host.get",
"params": {
"output": ["hostid"],
"selectHostGroups": "extend",
"filter": {
"host": [
"Zabbix server"
]
}
},
"id": 1
}Response:
{
"jsonrpc": "2.0",
"result": [
{
"hostid": "10085",
"hostgroups": [
{
"groupid": "2",
"name": "Linux servers",
"flags": "0",
"uuid": "dc579cd7a1a34222933f24f52a68bcd8"
},
{
"groupid": "4",
"name": "Zabbix servers",
"flags": "0",
"uuid": "6f6799aa69e844b4b3918f779f2abf08"
}
]
}
],
"id": 1
}Retrieving linked templates
Retrieve the IDs and names of templates linked to host "10084".
{
"jsonrpc": "2.0",
"method": "host.get",
"params": {
"output": ["hostid"],
"selectParentTemplates": [
"templateid",
"name"
],
"hostids": "10084"
},
"id": 1
}Response:
{
"jsonrpc": "2.0",
"result": [
{
"hostid": "10084",
"parentTemplates": [
{
"name": "Linux",
"templateid": "10001"
},
{
"name": "Zabbix Server",
"templateid": "10047"
}
]
}
],
"id": 1
}Retrieving hosts by template
Retrieve hosts that have the "10001" (Linux by Zabbix agent) template linked to them.
{
"jsonrpc": "2.0",
"method": "host.get",
"params": {
"output": ["hostid", "name"],
"templateids": "10001"
},
"id": 1
}Response:
{
"jsonrpc": "2.0",
"result": [
{
"templateid": "10001",
"hosts": [
{
"hostid": "10084",
"name": "Zabbix server"
},
{
"hostid": "10603",
"name": "Host 1"
},
{
"hostid": "10604",
"name": "Host 2"
}
]
}
],
"id": 1
}Searching by host inventory data
Retrieve hosts that contain "Linux" in the host inventory "OS" field.
{
"jsonrpc": "2.0",
"method": "host.get",
"params": {
"output": [
"host"
],
"selectInventory": [
"os"
],
"searchInventory": {
"os": "Linux"
}
},
"id": 1
}Response:
{
"jsonrpc": "2.0",
"result": [
{
"hostid": "10084",
"host": "Zabbix server",
"inventory": {
"os": "Linux Ubuntu"
}
},
{
"hostid": "10107",
"host": "Linux server",
"inventory": {
"os": "Linux Mint"
}
}
],
"id": 1
}Searching by host tags
Retrieve hosts that have tag "host-name" equal to "linux-server".
{
"jsonrpc": "2.0",
"method": "host.get",
"params": {
"output": ["hostid"],
"selectTags": "extend",
"evaltype": 0,
"tags": [
{
"tag": "host-name",
"value": "linux-server",
"operator": 1
}
]
},
"id": 1
}Response:
{
"jsonrpc": "2.0",
"result": [
{
"hostid": "10085",
"tags": [
{
"tag": "host-name",
"value": "linux-server",
"automatic": "0"
},
{
"tag": "os",
"value": "rhel-7",
"automatic": "0"
}
]
}
],
"id": 1
}Retrieve hosts that have these tags not only on host level but also in their linked parent templates.
{
"jsonrpc": "2.0",
"method": "host.get",
"params": {
"output": ["name"],
"tags": [
{
"tag": "os",
"value": "rhel-7",
"operator": 1
}
],
"inheritedTags": true
},
"id": 1
}Response:
{
"jsonrpc": "2.0",
"result": [
{
"hostid": "10623",
"name": "PC room 1"
},
{
"hostid": "10601",
"name": "Office"
}
],
"id": 1
}Searching host with tags and template tags
Retrieve a host with tags and all tags that are linked to parent templates.
{
"jsonrpc": "2.0",
"method": "host.get",
"params": {
"output": ["name"],
"hostids": 10502,
"selectTags": ["tag", "value"],
"selectInheritedTags": ["tag", "value"]
},
"id": 1
}Response:
{
"jsonrpc": "2.0",
"result": [
{
"hostid": "10502",
"name": "Desktop",
"tags": [
{
"tag": "host-name",
"value": "linux-server"
},
{
"tag": "os",
"value": "rhel-7"
}
],
"inheritedTags": [
{
"tag": "class",
"value": "os"
},
{
"tag": "target",
"value": "linux"
},
{
"tag": "os",
"value": "rhel-7"
}
]
}
],
"id": 1
}Searching hosts by problem severity
Retrieve hosts that have "Disaster" problems.
{
"jsonrpc": "2.0",
"method": "host.get",
"params": {
"output": ["name"],
"severities": 5
},
"id": 1
}Response:
Retrieve hosts that have "Average" and "High" problems.
{
"jsonrpc": "2.0",
"method": "host.get",
"params": {
"output": ["name"],
"severities": [3, 4]
},
"id": 1
}Response:
{
"jsonrpc": "2.0",
"result": [
{
"hostid": "20170",
"name": "Database"
},
{
"hostid": "20183",
"name": "workstation"
}
],
"id": 1
}See also
Source
CHost::get() in ui/include/classes/api/services/CHost.php.