Retrieval of license metric utilization (v2)

9.2.10 Available from 9.2.10.

You use the GET operation on the api/sam/v2/license_usage element to request information about utilization of license metrics by products that are installed in your infrastructure. By default, the results are returned for the computer group of the user whose token is used for authentication and cover the period for which data is aggregated in this group. They also include custom fields that were added to the All Metrics report.

Permissions

User You must have the View License Metrics permission to use this API.

Resource URL

https://hostname:port/api/sam/v2/license_usage

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, …
startdate
  • Use: Specifies the date starting from which the data is retrieved.
  • Values: YYYY-MM-DD
enddate
  • Use: Specifies the date until which the data is retrieved.
  • Values: YYYY-MM-DD
computerGroupId
  • Use: Specifies ID of the computer group for which data is retrieved.
  • Values: Integer
Response payload License Usage element
Response format application/json
Response codes

200 – OK

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

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.json

Available columns

Table 2. Available columns
Column Description Displayed by default Type
9.2.19 bundle_guid GUID of the FlexPoint bundle or Cloud Pak to which the product is assigned.   String
9.2.19 bundle_id Identifier of the FlexPoint bundle or Cloud Pak to which the product is assigned.   Integer
9.2.19bundle_metric_contribution When the product is a part of a FlexPoint bundle or a Cloud Pak, the column shows the number of license metric units that the particular product contributes to the overall metric quantity of the FlexPoint bundle or Cloud Pak to which that product is assigned.

It is the value from the hwm_quantity column multiplied by the conversion option that is specified for the particular product.

When the product is not a part of the FlexPoint bundle or a Cloud Pak, the column is empty.

  Integer
9.2.19 bundle_name Name of the FlexPoint bundle or Cloud Pak to which the product is assigned.   String
9.2.19 bundle_type Type of the bundle. Possible values:
  • -1 - Not a bundle
  • 0 - FlexPoint bundle
  • 1 - Cloud Pak
  Set of integers
custom_field_number Custom field that was added to the All Metrics report. To view the list of all custom fields, view the license_usage.json schema.   Various
9.2.35entitled Indicates whether a product, Cloud Pak or FlexPoint bundle was defined as your software entitlement (either by uploading part numbers or manually).   Boolean
9.2.14 hwm_peak_time The date and time when the highest number of metric units was used by a product in the selected period of time. If the value of hwm_quantity parameter is -1, the value of hwm_peak_time is meaningless.
Note: Retrieving hwm_peak_time might noticeably increase the time of retrieving the data.
  String
hwm_quantity The highest number of metric units that the product used within the period for which the data is retrieved. When metric quantity is not measured for a particular license metric, the value returned by the hwm_quantity parameter is -1. The value -1 cannot be used for sorting nor filtering. Integer
9.2.30 ibm_provided Specifies whether information that the product can use the license metric comes from the software catalog that is provided by IBM or was added manually. Possible values:
  • 0 - information from the software catalog that is provided by IBM
  • 1 - information added manually by a user
  Boolean
imported_part_numbers Part number that was imported to License Metric Tool. It represents the product that is listed in the product_name column and its license metric.   String
9.2.30 is_hybrid Indicates if the product can be deployed only on traditional VMs or both on traditional VMs and Kubernetes clusters. If both deployment options are possible, cumulative license usage might need to be combined from both License Metric Tool and License Service. Possible values:
  • 0 - software can be installed only on traditional VMs
  • 1 - software can be installed on traditional VMs and Kubernetes clusters
  Boolean
is_reaggregation_needed Specifies whether recalculation is needed for the product. The parameter cannot be used to filter or sort the results.   Boolean
metric_code_name Code name of the license metric. For explanation of the returned values, see: Metric IDs and code names. String
metric_id Identifier of the license metric. For explanation of the returned values, see: Metric IDs and code names.   String
metric_name Name of the license metric. The value that is returned by the metric_name parameter is provided as reference and can slightly differ from the value that is provided as a metric description in Table 1. It is best to retrieve metrics by using metric_id or metric_code_name parameters and then check the exact metric description by referring to Table 1.   String
9.2.27 product_bundle_ratio_divider When the product is a part of a FlexPoint bundle or a Cloud Pak, the column shows the divider of the ratio that is used to convert product license metrics to license metrics of the bundle.

For example, when IBM Security QRadar SOAR Users is installed as part of IBM Cloud Pak for Security, the conversion ratio is 5:1. The value of the product_bundle_ratio_divider column in this case would be 5.

  Integer
9.2.27 product_bundle_ratio_factor When the product is a part of a FlexPoint bundle or a Cloud Pak, the column shows the factor of the ratio that is used to convert product license metrics to license metrics of the bundle.

For example, when IBM Security QRadar SOAR Users is installed as part of IBM Cloud Pak for Security, the conversion ratio is 5:1. The value of the product_bundle_ratio_factor column in this case would be 1.

  Integer
product_family_guid GUID of the software product.   String
product_id Identifier of the software product.   Integer
product_name Name of the software product. String
threshold The maximum number of metric units that the product is entitled to use within a computer group. The value is set manually and is used to calculate the metric threshold delta.   Integer
threshold_delta It is calculated by subtracting metric quantity from the threshold. When you specify a threshold for a license metric that is not calculated, the value returned by the threshold_delta parameter is 2147483647. The value 2147483647 cannot be used for sorting nor filtering.   Integer

Query parameters

Table 3. Query parameters
Parameter Description Required Value
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 product name and threshold delta
URL?columns[]=product_name&columns[]=threshold_delta
  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 threshold delta
URL?order[]=threshold_delta 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
startdate Specify the date starting from which you want to retrieve the data. Specify it in the YYYY-MM-DD format. If you do not specify the filter, its default value is the date of the last successful import of data to License Metric Tool minus the number of days for which data is calculated in the computer group (90 days by default).
Example: Retrieve data starting from 14th July 2017
URL?startdate=2017-07-14
  Date
enddate Specify the date until which you want to retrieve the data. Specify it in the YYYY-MM-DD format. If you do not specify the filter, its default value is the date of the last successful import of data to License Metric Tool.
Example: Retrieve data from 1st October 2017 to 31st October 2017
URL?startdate=2017-10-01&enddate=2017-10-31
  Date
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>
Note: The license_usage REST API does not support nested filtering criteria.
Example 1: Retrieve software instances whose product name contains "BigFix" AND the threshold delta is below 0
URL?criteria={"and":[["product_name","contains","BigFix"],
["threshold_delta","<","0"] ] }

In case of the threshold, and custom_field_number fields, you can retrieve all entries for which the value is specified or for which it is not specified.

Example 2: Retrieve software products for which the threshold is specified
URL?criteria={"and":[["threshold","!=",]]}
Example 3: Retrieve software products for which the threshold is not specified
URL?criteria={"and":[["threshold","=",]]}

If you created custom fields that use the date values, you can retrieve data also for a period instead of a specific date. To do so, use last or next as <operator>, and then specify the time value in the following convention: PxD/PxW/PxM/PxY, where x is a number in the 1-999 range, and D, W, M, or Y is a designator that represents days, weeks, months, or years respectively.

Example 4: Retrieve software products for which entitlement ends within next month
URL?criteria={"and":[["custom_field_1","next","P1M"]]}

For more information about operators, see: Common connectors and operators.

  String

Example conversation - default columns

Request
GET https://hostname:port/api/sam/v2/license_usage
Request header
Accept: application/json 
Accept-Language: en-US
Token: <token>
Response header
Status Code: 200 OK
Content-Type: application/json
computerGroupId: 0
enddate: 2017-10-31
startdate: 2017-10-01
Response body
[{

"product_name": "WebSphere Service Registry and Repository",
"metric_code_name": "PVU_FULL_CAP",
"hwm_quantity": 480
}]

Example conversation - all columns

Request
GET https://hostname:port/api/sam/v2/license_usage?columns[]=product_id
&columns[]=product_name&columns[]=product_family_guid&columns[]=metric_id
&columns[]=metric_name&columns[]=metric_code_name&columns[]=hwm_quantity
&columns[]=threshold&columns[]=threshold_delta&columns[]=imported_part_numbers
&columns[]=is_reaggregation_needed&columns[]=bundle_name&columns[]=bundle_type
&columns[]=bundle_guid&columns[]=bundle_metric_contribution
&columns[]=ibm_provided
Request header
Accept: application/json 
Accept-Language: en-US
Token: <token>
Response body
[{
"product_id": 29258,
"product_name": "WebSphere Service Registry and Repository",
"product_family_guid": "3b31a72e-468d-47bb-825a-ea26c8e85199",
"metric_id": 3,
"metric_code_name": "PVU_FULL_CAP",
"metric_name": "PVU Full Capacity",
"hwm_quantity": 480,
"threshold": null,
"threshold_delta": null,
"imported_part_numbers": null,
"is_reaggregation_needed": 0
"bundle_name": null, 
"bundle_type": -1,
"bundle_guid": null,
"bundle_metric_contribution": null
"ibm_provided": 1
}]

Example conversation - additional column

Request
GET https://hostname:port/api/sam/v2/license_usage
?columns[]=product_name&columns[]=metric_name&columns[]=threshold_delta
Request header
Accept: application/json 
Accept-Language: en-US
Token: <token>
Response body
[{
"product_name": "WebSphere Service Registry and Repository",
"metric_name": "PVU Full Capacity",
"threshold_delta": 100
}]

Example conversation - custom field

To retrieve data from custom fields that were added to the All Metrics report, start by viewing the license_usage.json schema. The schema lists all columns, including custom fields. Identify the custom field from which you want to retrieve the data.
Request - check list of created custom fields
GET https://hostname:port/api/sam/v2/schemas/license_usage.json
Request header
Accept: application/json 
Accept-Language: en-US
Token: <token>
Response - list of all columns, including custom fields
[{
"product_name":
      {
       "type": "string",
       "description": "Name of the software product."
       },
...

"custom_field_1":
       {
       "type": "date",
       "title": "Entitlement End"
       }
}]
After you identify the name of the custom field, you can use it in the REST API request.
Request
GET https://hostname:port/api/sam/v2/license_usage
?columns[]=product_name&columns[]=custom_field_1
Request header
Accept: application/json 
Accept-Language: en-US
Token: <token>
Response body
[{
"product_name": "WebSphere Service Registry and Repository",
"custom_field_1": "2017-10-01"
}]

Example conversation - retrieving information about FlexPoint bundles and Cloud Paks

Request
GET https://hostname:port/api/sam/v2/license_usage
?columns[]=product_name&columns[]=bundle_name&columns[]=bundle_type
&columns[]=bundle_metric_contribution&criteria={"and":[["bundle_type","in","[0,1]"]]}
Request header
Accept: application/json 
Accept-Language: en-US
Token: <token>
Response body
[{
"product_name": "IBM WebSphere Application Server Network Deployment",
"bundle_name": "IBM Cloud Pak for Applications"
"bundle_type": "1"
"bundle_metric_contribution": "100"
}]