Retrieval of license usage information per server (v2)

11.0.7.0 Available from 11.0.7.0. Use the GET operation on the api/sam/v2/license_usage_per_server element to request information about utilization of license metrics per server on a specific day.

Note: You can use this REST API to retrieve data about the following license metrics:
  • Processor Value Unit: PVU_FULL_CAP, PVU_SUB_CAP
  • Resource Value Unit Managed Activated Processor Cores: RVU_FULL_CAP, RVU_SUB_CAP
  • Virtual Processor Core: VIRTUAL_PROCESSOR_CORE

Permissions

User You must have the View Hardware Inventory and View License Metric permissions to use this API.

Resource URL

https://hostname:port/api/sam/v2/license_usage_per_server?date=date

Resource information

Table 1. Resource information
Operation details Description
HTTP method GET
Request headers
Header
Accept-Language (optional)
Values
en-US (only English is supported)

Negotiates the language of the response. If the header is not specified, the content is returned in the server language.
Request format application/json
Response headers
Header
Content-Type
Values
application/json

Specifies the content type of the response.
Header
Content-Language
Values
en-US, …

Specifies the language of the response content. If the header is not specified, the content is returned in the server language.
Response payload License Usage Per Server element
Response format application/json
Response codes

200 – OK

400 – "Bad Request" if a query parameter contains errors or is missing

403 – "Forbidden" if the current user does not have access to a particular computer group

412 – "Precondition Failed" if license usage calculations are not enabled for the particular computer group

Schema description

To retrieve the list of all columns that are returned by this REST API together with their descriptions, use the following request.
GET api/sam/v2/schemas/license_usage_per_server.json?token=token

Available columns

Table 2. Available columns
Column Description Displayed by default Type
product_id Identifier of the software product. ✓ Integer
product_name Name of the software product. ✓ String
product_family_guid GUID of the software product. String
metric_id Identifier of the license metric. For explanation of the returned values, see: Metric IDs and code names. ✓ String
metric_code_name Code name of the license metric. ✓ String
server_id Identifier of the server. ✓ Integer
hwm_quantity The number of metric units that the product used on a server during the day for which the data is retrieved. ✓ Integer
hwm_cores The number of processor cores that the product used on a server during the day for which the data is retrieved. ✓ Integer
bundle_id ID of the Product Bundle to which the product is assigned. ✓ Integer
bundle_name Name of the Product Bundle to which the product is assigned. ✓ String
bundle_guid GUID of the Product Bundle to which the product is assigned. String

Applicable associations

You can additionally retrieve data from the following association:

Query parameters

Table 3. Query parameters
Parameter Description Required Value
date Specify the day for which you want to retrieve the data. Use the following format: YYYY-MM-DD. ✓ String
computerGroupId Specify ID of the computer group for which you want to retrieve the data. If you do not specify this parameter, the data is retrieved for the computer group of the user whose token is used for authentication. If you specify the parameter, you can retrieve the data for a subgroup of this computer group.

To view IDs of computer groups, log in to BigFix Inventory and go to Reports > Computer Groups. Then, hover of the Manage Report View icon Manage Report View icon, click Configure View, and select the ID column to display it on the report.

Example: Retrieve data for computer group 5
URL?computerGroupId=5
 Integer
columns Specify which columns to retrieve. If you do not specify this parameter, only default columns are retrieved.
Example: Retrieve product name and server ID
URL?columns[]=product_name&columns[]=server_id
 String
order Specify how to sort the retrieved data. The default direction for sorting columns is ascending. If you want to specify a descending sort, append desc to the column name.
Example: Order by product name
URL?order[]=product_name desc
 Alphanumeric
limit Specify the number of rows to retrieve. If you omit this parameter, all rows are retrieved.
Example: Retrieve 100 records 
URL?limit=100
 Numeric
offset Specify the number of rows to skip for retrieving results. You can use it together with the limit parameter to paginate results.
Example: Retrieve 50 records starting after record 150
URL?limit=50&offset=150
 Numeric
token A unique user authentication identifier. 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 User icon, and click Profile. Then, click Show token. ✓ Alphanumeric
criteria Retrieve records which match specific conditions. The parameter should have the following structure, written in one line: 
<criteria> ::= <left-brace> <boolean-operator> <colon> <left-bracket> 
<criterion> [{ <comma> <criterion> }...] <right-bracket> <right-brace>
<boolean-operator> ::= "and" | "or"
<criterion> ::= <criteria> | <left-bracket> <column> <comma> <operator> <comma> <value> <right-bracket>
<column> ::= <json-string>
<operator> ::= <json-string>
<value> ::= <json-array> | <json-string> | <json-number> | <json-null>
Example:
URL?criteria={"and":[["product_name","contains","DB2"],
           ["hwm_quantity",">","100"] ] }
 String

Example conversation

Request
GET api/sam/v2/license_usage_per_server?date=2025-09-17?token=7adc3efb175e2bc0f4484bdd2efca54a8fa04623
Host: localhost:9081 
Accept: application/json 
Accept-Language: en-US
Response header
Status Code: 200 OK
Content-Type: application/json
Response body
[{
  "product_id": 24,
  "metric_id": 3,
  "bundle_id": 0,
  "server_id": 19,
  "product_name": "IBM InfoSphere QualityStage Address Verification Interface",
  "metric_code_name": "PVU_FULL_CAP",
  "bundle_name": null,
  "hwm_quantity": 8800,
  "hwm_cores": 88,
  "server": {
    "name":"LENOVO XXXXXX.hcl.com"
  }
}]