Retrieval of license usage information per server (v2)

Edit online

9.2.24 Available from 9.2.24.

You 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: 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
Accept-Language (optional)
  • Use: Used to negotiate the language of the response. If this header is not specified, the content is returned in the server language.
  • Values: en-US (only English is supported)
Token
  • Use: Used to authenticate REST API requests. The header is required when you set the value of the api_token_in_url_enabled parameter to false. Otherwise, you can specify the token in the request header or in the URL. For more information, see: Authenticating REST API requests.
  • Values: an alphanumeric string that is generated in License Metric Tool
Request format application/json
Response headers
Content-Type
  • Use: Specifies the content type of the response.
  • Values: application/json
Content-Language
  • Use: Specifies the language of the response content. If this header is not specified, the content is returned in the server language.
  • Values: en-US, …
Response payload Computer Systems element
Response format application/json
Response codes

200 – OK

500 – “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

428 – “Precondition Required” 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 https://hostname:port/api/sam/v2/schemas/license_usage_per_server.json

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. ✓ String
metric_code_name Code name of the license metric. ✓ String
bundle_id Identifier of the FlexPoint bundle or Cloud Pak to which the product is assigned. ✓ Integer
bundle_name Name of the FlexPoint bundle or Cloud Pak to which the product is assigned. ✓ String
bundle_guid GUID of the FlexPoint bundle or Cloud Pak to which the product is assigned.   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

Applicable associations

You can additionally retrieve data from the following association:

For more information about how to use API associations, see: REST API associations.

Important: All associations provide data about items that currently exist in the infrastructure. For removed computers and uninstalled software, these associations return null.
Request
GET https://hostname:port/api/sam/v2/license_usage_per_server
?date=2021-04-28&columns[]=server.id&columns[]=server.name&columns[]=server.type
&columns[]=server.hardware_serial_number&columns[]=server.hardware_vendor
&columns[]=server.hardware_model&columns[]=server.hardware_type&columns[]=server.total_processors
&columns[]=server.cores&columns[]=server.processor_brand_string&columns[]=server.processor_model
&columns[]=server.processor_type&columns[]=server.processor_vendor&columns[]=server.pvu_per_core
&columns[]=server.default_pvu_value&columns[]=server.custom_pvu_value&columns[]=server.active_computers
Request header
Accept: application/json 
Accept-Language: en-US
Token: <token>
Response body
[{
"server":
    {
    "id":19,
    "name":"LENOVO  XXXXXX.ibm.com",
    "type":0,
    "hardware_serial_number":"XXXXXX.ibm.com",
    "hardware_vendor":"LENOVO",
    "hardware_model":"Lenovo System x3850 X6 -[6241AC3]",
    "hardware_type":null,
    "total_processors":4,
    "cores":88,
    "processor_brand_string":"Intel(R) Xeon(R) CPU E7-8880 v4 @ 2.20GHz",
    "processor_model":"E3-12xx E7-28xx E7-48xx E7-88xx",
    "processor_type":"Multi-core",
    "processor_vendor":"Intel(R)",
    "pvu_per_core":100,
    "default_pvu_value":0,
    "custom_pvu_value":0,
    "active_computers":3
    }
}]

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. ✓  
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 License Metric Tool and go to Reports > Computer Groups. Then, hover over Configure, 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 GUID of the FlexPoint bundle or Cloud Pak to which the product is assigned
URL?columns[]=bundle_guid
   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 the number of metric units that the product used on a server during the day for which the data is retrieved
URL?order[]=hwm_quantity 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
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 - default columns

Request
GET https://hostname:port/api/sam/v2/license_usage_per_server?date=2021-04-28
Request header
Accept: application/json 
Accept-Language: en-US
Token: <token>
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.ibm.com"}
}]

Example conversation - all columns

Request
GET https://hostname:port/api/sam/v2/license_usage_per_server?date=2021-04-28
?columns[]=product_id&columns[]=product_name&columns[]=product_family_guid
&columns[]=metric_id&columns[]=metric_code_name&columns[]=bundle_id
&columns[]=bundle_name&columns[]=bundle_guid&columns[]=server_id
&columns[]=hwm_quantity&columns[]=hwm_cores&columns[]=server.name
&date=2021-04-28
Request header
Accept: application/json 
Accept-Language: en-US
Token: <token>
Response body
[{
"product_id":24,
"metric_id":3,
"bundle_id":0,
"server_id":19,
"product_name":"IBM InfoSphere QualityStage Address Verification Interface",
"product_family_guid":"35a5f4e1-ce32-4ceb-b1f5-5d39ae300eb1",
"metric_code_name":"PVU_FULL_CAP",
"bundle_name":null,
"bundle_guid":null,
"hwm_quantity":8800,
"hwm_cores":88,
"server":
    {"name":"LENOVO  XXXXXX.ibm.com"}
}]

Example conversation - retrieving detailed license metric utilization for a selected software product

You can use this REST API to retrieve data about all products that are installed on the computers in your environment with a single API call. In this case, the data is retrieved for all products only for the day that is specified in the date parameter. You can also use the api/sam/v2/license_usage_per_server REST API in combination with the api/sam/v2/license_usage REST API.

In the first step, use the api/sam/v2/license_usage REST API to retrieve overall license metric utilization for a selected period.
Request - retrieve overall license metric utilization for a selected period
GET https://hostname:port/api/sam/v2/license_usage_per_server
?startdate=2021-03-01&enddate=2021-03-31&columns[]=product_name
&columns[]=metric_code_name&columns[]=hwm_quantity&columns[]=product_id
&columns[]=metric_id&columns[]=bundle_id&columns[]=hwm_peak_time
Request header
Accept: application/json 
Accept-Language: en-US
Token: <token>
Response body
[{
"product_id":24,
"product_name":"IBM InfoSphere QualityStage Address Verification Interface",
"metric_id":3,
"metric_code_name":"PVU_FULL_CAP",
"bundle_id":0,
"hwm_quantity":8800,
"hwm_peak_time":"2021-04-26T23:07:19Z"
}]
In the second step, use values from the product_id, metric_id, and bundle_id parameters to retrieve detailed license metric utilization for a particular software product per server for the day when the utilization was the highest (the date that was returned in the hwm_peak_time parameter).
Request - retrieve detailed license metric utilization
GET https://hostname:port/api/sam/v2/license_usage_per_server
?date=2021-04-26&criteria{"and":[["product_id","=","24"],["metric_id","=","3"],
[bundle_id,"equals","0"]]}
Request header
Accept: application/json 
Accept-Language: en-US
Token: <token>
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.ibm.com"
}]