Determining license usage for selected computer systems

You can narrow down the results of your API requests to retrieve data only from selected computer systems. This approach is recommended if you want to quickly target specific information.

Before you begin

Each API request must be authenticated with the token parameter. You can retrieve it by using REST API for retrieving authentication token. You can also log in to BigFix Inventory, hover over the User icon , and click Profile. Then, click Show token.
To obtain the list of query parameters to narrow down your results and the list of available columns, see the information related to a particular API type.

Procedure

Retrieve selected computer systems by querying for their ID:

https://hostname:port/api/sam/computer_systems?
token=token&criteria={"or":[["id","=","1"],["id","=","2"]]}

Result: Each computer system has a different id. You can later use this id to create a match between your software instances and computer systems. In API for software instances and license usage, this id is represented by the computer_system_id column.

{
    "id": 2,
    "parent_id": 175,
    "type": "virtual",
    "os": "Win2008R2 6.1.7601",
    "host_name": "NC9128109187",
    "dns_name": "NC9128109187",
    "ip_address": [
        "9.128.109.187"],
    "last_seen": "2014-06-06T03:56:39Z",
    "hardware_manufacturer": "-",
    "hardware_model": "-",
    "hardware_serial_number": "TLM_VM_4236ac43",
    "processor_type": "Multi-core",
    "processor_brand": "Xeon(R), 3 or 4 Socket",
    "processor_vendor": "Intel(R)",
    "processor_model": "E3-12xx, E7-28xx, E7-48xx",
    "partition_cores": "1.0",
    "server_processors": 1,
    "server_cores": 1
}

Retrieve software instances for selected computer systems by querying for their ID:
The following example retrieves the computer_system_id and software_title_name columns so that you can recognize which software is installed on which computer system. If you want to retrieve complete information, append the URL with the names of all columns. You can find the column names in response body:
```
https://hostname:port/api/sam/software_instances?
token=token&
criteria={"or":[["computer_system_id","=","1"],["computer_system_id","=","2"]]}
&columns[]=computer_system_id&columns[]=catalog_dimension.software_title_name
```
Result: Each software instance contains a computer_system_id column that represents an ID of a computer that a particular instance is installed on. Use this column to match your software instances with computer systems. For example, if rows 152-155 contain a computer_system_id=2 column, it means that all those software instances are installed on a computer system with ID 2.
```
{
    "computer_system_id": 2,
    "catalog_dimension": {
        "software_title_name": "BigFix Inventory"
    }
```
Retrieve the license usage for selected computer systems by querying for their ID. Append the URL with the software_title_dimension.name column to be able to recognize the name of the software that the license usage is presented for.
The following example retrieves the computer_system_id, metric_name, peak_value, and software_title_dimension.name columns. If you want to retrieve complete information, append the URL with the names of all columns. You can find the column names in response body:
```
https://hostname:port/api/sam/license_usages?
token=token&
criteria={"or":[["computer_system_id","=","1"],["computer_system_id","=","2"]]}
&columns[]=computer_system_id&columns[]=metric_name&columns[]=peak_value&
columns[]=software_title_dimension.name
```
Result: Each record contains a computer_system_id column that represents an ID of a computer for which the license usage is calculated. Use this column to match the license usage with computer systems. For example, if rows 152-155 contain a computer_system_id=2 column, it means that all those license usage records are presented for a computer system with ID 2. The peak_value column represents the peak license usage (over last 90 days) for a particular software title (which is described by software_title_dimension.name). The metric_name column allows you to recognize whether the license type is PVU or RVU, full or subcapacity.
```
{
    "computer_system_id": 2,
    "metric_name": "RVU_SUB_CAP",
    "peak_value": 2,
    "software_title_dimension": {
        "name": "BigFix Inventory"
}}
```

Results

You retrieved the list of software instances that are installed on a particular computer system, as well as the license usage that they generate. This information is only a part of the total license usage generated on all your computer systems. To determine the total license usage for your environment, see Determining license usage for all computer systems.