Showing results for 
Search instead for 
Did you mean: 
Cisco Employee
Cisco Employee

Welcome to part 4 of the "APIC-EM API productivity series" for network engineers getting started in API and scripting.

Earlier blogs on APIC-EM covered

  1. /network-device – all attributes of network-devices (blog1)
  2. /interface/network-device – all interfaces  (and hosts) on a network-device e.g. a switch (blog2)
  3. /license-info - all licencing information for a network-device (blog3)

By this stage of the blog series, I am going to assume you are familiar with swagger (API documentation tool) and the location of the github repository where I have shared the code samples.

#4 find my host

As mentioned earlier, the controller has a table of all hosts that are connected to network-devices. This information is kept updated when link up/down traps are enabled on switches and wireless Lan controllers (WLC). See the configuration guide for the commands to enable this on the network-devices.

This means that I can use the controller as an accurate source of information about hosts connected to the network and locate them.  This example allows a search by host mac address or ip address.


Navigate to the "/host" URL as in blog#2.  In this case you are going to use the "hostIp" parameter.   From blog #2, you know there is a host with IP address of "".  Enter this in, along with scope.


You will get the following output, showing the network-device and the interface this host is connected to.


You can also do a lookup by MAC address.  Use the "hostMac" parameter and set it to "e8:9a:8f:7a:22:99".  You will get the same output as before.



The script "" allows a search for a host via either MAC address or IP address. The three examples below illustrate the ways this can be done:

  1. 1) This example shows a lookup by MAC address.  You can see the host IP|MAC as well as the ip address of the network-device ( and the interface (GigabitEthernet1/0/47) and the vlan (200)
  2. 2) The second example is the same as the first, just a lookup by hostip.  As expected it shows the same information as the previous call.
  3. 3) This example is for a wireless client.  It shows the Controller the host is connected to as well (along with model and software version) as well as the AP the host is connected to.

$ ./ --mac e8:9a:8f:7a:22:99|e8:9a:8f:7a:22:99 wired ->|GigabitEthernet1/0/47 vlan:200

$ ./ --ip|e8:9a:8f:7a:22:99 wired ->|GigabitEthernet1/0/47 vlan:200

$ ./ --mac 00:24:d7:43:59:d8|00:24:d7:43:59:d8 wireless -> Campus-WLC-5508 AIR-CT5508-K9( ->  AP7081.059f.19ca vlan:600

Looking at the code

There are three API calls used in this code.

  1. "host?hostIp=%s" which does a lookup by hostIp address.  This is used when an IP address is supplied
  2. "host?hostMac=%s" which is a lookup by MAC address
  3. "network-device/%s" we have seen before.  This is looking up a network-device by UUID, in this case to get some extra information about the Wireless LAN Controller the host is connected to.

def get_host(ip=None, mac=None):
     if ip is not None:
          url = "host?hostIp=%s" % ip
     elif mac is not None:
          url = "host?hostMac=%s" % mac
      return get_url(url)

def get_wlc(id):
      return get_url("network-device/%s" % id)

The other concept this code shows is the use of argument parsing to allow the "—mac" and "—ip" options to be used.  Argparse is a python package for argument parsing ( ).

parser = ArgumentParser(description='Select options.')
parser.add_argument('--ip', type=str,help="ip address")
parser.add_argument('--mac', type=str,help="mac address")
parser.add_argument('-v', action='store_true',help="verbose")
args = parser.parse_args()

This is a very simple tool you can use for troubleshooting.  Some improvements could include:

  • Change the script so that it takes a single argument that is either a MAC or IP address and intelligently (based on syntax of the argument) determine if a MAC search or IP search is required.
  • Embed this into a python web framework like Flask to turn this into a web page. Happy to provide an example of this, if people are interested.
  • Provide a "refresh" option where the script will refresh the location every 5mins to track a host connectivity status.

What Next?

This blog covered the forth of the useful API /host . The final blog in the series will look /flow-analysis, an API to do a path trace between hosts on the network.  It also provides stats on interfaces, QoS, Perfmon and ACL trace.

In the meantime, if you would like to learn more about APIC-EM, you could visit Cisco Devnet.  All of the code samples can be found in this Github repository.

Thanks for reading


Getting Started

Find answers to your questions by entering keywords or phrases in the Search bar above. New here? Use these resources to familiarize yourself with the community: