Retrieval of license metric utilization (v2)

Edit online

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
bundle_guid	GUID of the FlexPoint bundle or Cloud Pak to which the product is assigned.		String
bundle_id	Identifier of the FlexPoint bundle or Cloud Pak to which the product is assigned.		Integer
bundle_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
bundle_name	Name of the FlexPoint bundle or Cloud Pak to which the product is assigned.		String
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
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
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		Integer
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
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		Integer
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
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
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	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"
}]