---
title: "Queryhost - Listing"
description: ""
url: "https://docs.itrsgroup.com/docs/opsview/6.11.7/rest-api/queryhost/api-queryhost-listing/index.html"
---
## GET request

This can be used to query interfaces against an existing Opsview Host only.
The query is always run from the Monitoring Cluster that is monitoring the Host.

The required parameters are one of the following:

- `hostname` — name of the host in Opsview.
- `hostid` — ID of the host taken from the `id` column in the `opsview_hosts` table in the `runtime` database.


**Note**


Ensure that IDs are sourced from the correct database and table as they can differ for the same Opsview Host.



## POST request

This can be used to query interfaces against existing Opsview Hosts and devices that are not currently monitored by Opsview.
It allows you to specify a Monitoring Cluster for the query and test device connectivity.

### Existing Opsview Host

The required parameters are:

- `snmp_version` — any of 1, 2c, or 3.
- `hostid` — ID of the host taken from the `id` column in the `hosts` table in the `opsview` database.


**Note**


Ensure that IDs are sourced from the correct database and table as they can differ for the same Opsview Host.



Depending on the SNMP version, additional required parameters are:

#### Version 1 and 2c

- `snmp_community` — SNMP community string.

#### Version 3

- `snmpv3_username` — SNMPv3 username.
- `snmpv3_authpassword` — SNMPv3 authentication password.
- `snmpv3_authprotocol` — SNMPv3 authentication protocol. Can be any of `md5`, `sha`.
- `snmpv3_privpassword` — SNMPv3 privacy password.
- `snmpv3_privprotocol` — SNMPv3 privacy protocol. Can be any of `des`, `aes`, `aes128`, `aes256`, `aes256c`.


**Warning**


When setting the `snmpv3_privprotocol` parameter, the `aes256` and `aes256c` options are only fully supported on some operating systems. For more information, see [SNMP Privacy Protocol Support](https://docs.itrsgroup.com/docs/opsview/6.11.7/prerequisites/snmp-requirements/index.html#snmp-privacy-protocol-support).



For any SNMP version, optional parameters are:

- `testconnection` — 0 to run a full interface query. 1 to just test the connection and return the system description. This defaults to 0.
- `msid` - ID of the Monitoring Cluster that the query is to be run from. 1 is the Master Monitoring Server (orchestrator). This does not have to match the Monitoring Cluster currently monitoring the existing Host, but that is used as the default.
- `snmp_port` — port to connect to on the SNMP device. This defaults to 161.
- `snmp_max_msg_size` — max SNMP message size in bytes. This is unset by default. See [SNMP Message Size](https://docs.itrsgroup.com/docs/opsview/6.11.7/configuration/hosts-groups/host/index.html#snmp-message-size).
- `snmp_use_getnext` — 1 to use SNMP GetNext instead of SNMP GetBulk to query; 0 to use SNMP GetBulk. This defaults to 0. See [Use SNMP GetNext](https://docs.itrsgroup.com/docs/opsview/6.11.7/configuration/hosts-groups/host/index.html#use-snmp-getnext).
- `snmp_use_ifname` — 1 to base interface names on `ifName` instead of `ifDescr`; 0 to use `ifDescr`. This defaults to 0. See [Use SNMP ifName](https://docs.itrsgroup.com/docs/opsview/6.11.7/configuration/hosts-groups/host/index.html#use-snmp-ifname).
- `tidy_ifdescr_level` — `ifDescr` modification level such as 3. This defaults to turned off. See [Modify ifDescr Level](https://docs.itrsgroup.com/docs/opsview/6.11.7/configuration/hosts-groups/host/index.html#modify-ifdescr-level).

### Unmonitored device

Required parameters are:

- `snmp_version` — any of 1, 2c, or 3.
- `ip` — FQDN or IP address of device.
- `msid` - ID of the Monitoring Cluster that the query is to be run from. 1 is the Master Monitoring Server (orchestrator).

Depending on the SNMP version, additional required parameters are:

#### Version 1 and 2c

- `snmp_community` — SNMP community string.

#### Version 3

- `snmpv3_username` — SNMPv3 username.
- `snmpv3_authpassword` — SNMPv3 authentication password.
- `snmpv3_authprotocol` — SNMPv3 authentication protocol. Can be any of `md5`, `sha`.
- `snmpv3_privpassword` — SNMPv3 privacy password.
- `snmpv3_privprotocol` — SNMPv3 privacy protocol. Can be any of `des`, `aes`, `aes128`, `aes256`, `aes256c`.


**Warning**


When setting the `snmpv3_privprotocol` parameter, the `aes256` and `aes256c` options are only fully supported on some operating systems. For more information, see [SNMP Privacy Protocol Support](https://docs.itrsgroup.com/docs/opsview/6.11.7/prerequisites/snmp-requirements/index.html#snmp-privacy-protocol-support).



For any SNMP version, optional parameters are:

- `testconnection` — 0 to run a full interface query. 1 to just test the connection and return the system description. This defaults to 0.
- `snmp_port` — port to connect to on the SNMP device. This defaults to 161.
- `snmp_max_msg_size` — max SNMP message size in bytes. This is unset by default. See [SNMP Message Size](https://docs.itrsgroup.com/docs/opsview/6.11.7/configuration/hosts-groups/host/index.html#snmp-message-size).
- `snmp_use_getnext` — 1 to use SNMP GetNext instead of SNMP GetBulk to query; 0 to use SNMP GetBulk. This defaults to 0. See [Use SNMP GetNext](https://docs.itrsgroup.com/docs/opsview/6.11.7/configuration/hosts-groups/host/index.html#use-snmp-getnext).
- `snmp_use_ifname` — 1 to base interface names on `ifName` instead of `ifDescr`; 0 to use `ifDescr`. This defaults to 0. See [Use SNMP ifName](https://docs.itrsgroup.com/docs/opsview/6.11.7/configuration/hosts-groups/host/index.html#use-snmp-ifname).
- `tidy_ifdescr_level` — `ifDescr` modification level such as 3. This defaults to turned off. See [Modify ifDescr Level](https://docs.itrsgroup.com/docs/opsview/6.11.7/configuration/hosts-groups/host/index.html#modify-ifdescr-level).

## Listing interfaces

Output of a list response:

```
    {
      interfaces => [
        {
          discards_critical => 15,
          discards_warning => "",
          errors_critical => 10,
          errors_warning => "",
          extra_info => "alias:'' speed:'' link:'' status:''",
          id => 0,
          ifAlias => undef,
          ifDescr => "",
          ifLink => undef,
          ifSpeed => undef,
          ifStatus => undef,
          interfacename => "",
          throughput_critical => "0:50%",
          throughput_warning => "",
        },
        {
          discards_critical => "",
          discards_warning => "",
          errors_critical => "",
          errors_warning => "",
          extra_info => "alias:'192.168.13.0 network' speed:'10Mbit/s' link:'up' status:'up'",
          id => 1,
          ifAlias => "192.168.13.0 network",
          ifDescr => "Ethernet0/0",
          ifLink => "up",
          ifSpeed => "10Mbit/s",
          ifStatus => "up",
          interfacename => "Ethernet0/0",
          throughput_critical => "",
          throughput_warning => "",
        },
        {
          discards_critical => "",
          discards_warning => "",
          errors_critical => "",
          errors_warning => "",
          extra_info => "alias:'192.168.21.0 network' speed:'10Mbit/s' link:'down' status:'down'",
          id => 3,
          ifAlias => "192.168.21.0 network",
          ifDescr => "Ethernet0/1",
          ifLink => "down",
          ifSpeed => "10Mbit/s",
          ifStatus => "down",
          interfacename => "Ethernet0/1",
          throughput_critical => "",
          throughput_warning => "",
        },
        {
          discards_critical => "",
          discards_warning => "",
          errors_critical => "",
          errors_warning => "",
          extra_info => "alias:'' speed:'8Gbit/s' link:'up' status:'up'",
          id => 5,
          ifAlias => "",
          ifDescr => "Loopback0",
          ifLink => "up",
          ifSpeed => "8Gbit/s",
          ifStatus => "up",
          interfacename => "Loopback0",
          throughput_critical => "",
          throughput_warning => "",
        },
        {
          discards_critical => "",
          discards_warning => "",
          errors_critical => "",
          errors_warning => "",
          extra_info => "alias:'' speed:'10Gbit/s' link:'up' status:'up'",
          id => 4,
          ifAlias => "",
          ifDescr => "Null0",
          ifLink => "up",
          ifSpeed => "10Gbit/s",
          ifStatus => "up",
          interfacename => "Null0",
          throughput_critical => "",
          throughput_warning => "",
        },
        {
          discards_critical => "",
          discards_warning => "",
          errors_critical => "",
          errors_warning => "",
          extra_info => "alias:'192.168.250.0 network' speed:'2Mbit/s' link:'up' status:'down'",
          id => 2,
          ifAlias => "192.168.250.0 network",
          ifDescr => "Serial0/0",
          ifLink => "up",
          ifSpeed => "2Mbit/s",
          ifStatus => "down",
          interfacename => "Serial0/0",
          throughput_critical => "",
          throughput_warning => "",
        },
        {
          discards_critical => "",
          discards_warning => "",
          errors_critical => "",
          errors_warning => "",
          extra_info => "alias:'' speed:'100Mbit/s' link:'up' status:'up'",
          id => 7,
          ifAlias => "",
          ifDescr => "Virtual-Access1",
          ifLink => "up",
          ifSpeed => "100Mbit/s",
          ifStatus => "up",
          interfacename => "Virtual-Access1",
          throughput_critical => "",
          throughput_warning => "",
        },
        {
          discards_critical => "",
          discards_warning => "",
          errors_critical => "",
          errors_warning => "",
          extra_info => "alias:'' speed:'100Mbit/s' link:'up' status:'down'",
          id => 8,
          ifAlias => "",
          ifDescr => "Virtual-Access2",
          ifLink => "up",
          ifSpeed => "100Mbit/s",
          ifStatus => "down",
          interfacename => "Virtual-Access2",
          throughput_critical => "",
          throughput_warning => "",
        },
        {
          discards_critical => "",
          discards_warning => "",
          errors_critical => "",
          errors_warning => "",
          extra_info => "alias:'' speed:'100Mbit/s' link:'up' status:'down'",
          id => 6,
          ifAlias => "",
          ifDescr => "Virtual-Template1",
          ifLink => "up",
          ifSpeed => "100Mbit/s",
          ifStatus => "down",
          interfacename => "Virtual-Template1",
          throughput_critical => "",
          throughput_warning => "",
        },
      ],
      system_description => "Cisco Internetwork Operating System Software",
    }
```


**Note**


The `id => 0` interface is used to return the default thresholds for all interfaces; it is not a real interface.



## Testing connection output example

```
    {
        system_description => "Cisco Internetwork Operating System Software",
    }
```


