Skip to content
The XG Series hardware appliances will reach end-of-life (EOL) on March 31, 2025. Click here to see the XG to XGS migration documentation.

Page permalink

Always use the following permalink when referencing this page. It will remain unchanged in future help versions.

https://docs.sophos.com/nsg/sophos-firewall/21.0/Help/en-us/webhelp/onlinehelp/index.html?contextId=api-get-requests

API request for object usage

You can use API GET requests to retrieve the names and usage count of configurations in which an object is used. Currently, the response doesn't include the dependent configurations.

Learn about the objects, the corresponding XML tags, and the syntax with examples for making API requests and applying filters.

For more information on object usage, see Object usage.

Objects

You can use the GET request to retrieve some objects.

Host and service objects

Object XML tag
IP hosts <IPHostStatistics></IPHostStatistics>
IP host groups <IPHostGroupStatistics></IPHostGroupStatistics>
MAC hosts <MACHostStatistics></MACHostStatistics>
FQDN hosts <FQDNHostStatistics></FQDNHostStatistics>
FQDN host groups <FQDNHostGroupStatistics></FQDNHostGroupStatistics>
Country groups <CountryGroupStatistics></CountryGroupStatistics>
Services <ServicesStatistics></ServicesStatistics>
Service groups <ServiceGroupStatistics></ServiceGroupStatistics>

Network and routing objects

Object XML tag
Interfaces <InterfaceStatistics></InterfaceStatistics>
Zones <ZoneStatistics></ZoneStatistics>
Gateways <GatewayStatistics></GatewayStatistics>
SD-WAN profiles <SDWANProfileStatistics></SDWANProfileStatistics>

GET requests

Syntax

The syntax to use in web browsers to get the usage count for IP hosts is as follows:

https://<Firewall IP address or hostname>:<Firewall's port>/webconsole/APIController?reqxml=<Request><Login><Username><Web admin console administrator's username></Username><Password><Administrator's password></Password></Login><Get><IPHostStatistics></IPHostStatistics></Get></Request>
Example 
https://myfirewall.com:4444/webconsole/APIController?reqxml=<Request><Login><Username>admin</Username><Password>@Passw0rd</Password></Login><Get><IPHostStatistics></IPHostStatistics></Get></Request>

For other objects, use this syntax with the corresponding object.

Filters

You can use the following filters in the API GET request for the object's name and usage count.

Fieldname Filters
Name like, not like, startswith, in, =, !=
Usage count in, =, !=, >, >=

The filters show the usage count as follows:

Filters Criteria
like Name contains the letters you specify.
not like Name doesn't contain the letters you specify.
startswith Name starts with the letters you specify.
in

Exact matches of the name or usage values you specify.

Enter comma-separated values.
= Exact name or usage value you specify.
!= Objects that don't match the exact name or usage value you specify.
> Greater than the usage value you specify.
>= Greater than or equal to the usage value you specify.

The syntax to use a filter for an IP host's name is as follows:

https://<Firewall's IP address or hostname>:<Firewall's port>/webconsole/APIController?reqxml=<Request><Login><Username><Web admin console administrator's username></Username><Password><Administrator's password></Password></Login><Get><IPHostStatistics><Filter><key name="Name" criteria="like"><Name value></key></Filter></IPHostStatistics></Get></Request>
Example 
https://myfirewall.com:4444/webconsole/APIController?reqxml=<Request><Login><Username>admin</Username><Password>@Passw0rd</Password></Login><Get><IPHostStatistics><Filter><key name="Name" criteria="like">Internet</key></Filter></IPHostStatistics></Get></Request>

The syntax to use a filter for an IP host's usage is as follows:

https://<Firewall's IP address or hostname>:<Firewall's port>/webconsole/APIController?reqxml=<Request><Login><Username><Web admin console administrator's username></Username><Password><Administrator's password></Password></Login><Get><IPHostStatistics><Filter><key name="Usage" criteria="in"><Usage value>,<Usage value></key></Filter></IPHostStatistics></Get></Request>
Example 
https://myfirewall.com:4444/webconsole/APIController?reqxml=<Request><Login><Username>admin</Username><Password>@Passw0rd</Password></Login><Get><IPHostStatistics><Filter><key name="Usage" criteria="in">1,2,3</key></Filter></IPHostStatistics></Get></Request>