Retrieval of PVU and RVU license usage reports

You use the GET operation on the reports/metrics element to request information about the current PVU and RVU license usage reports.

An icon representing a user. You must have the View License Metrics permission to perform this task.

Table 1. Operation descriptions

The table consists of two columns and 15 rows. For the eleventh row there are two levels.
Operation details Description
Operation GET/reports/metrics
Purpose Returns usage information about all licenses.
HTTP method GET
Resource URI https://server_host_name:port_number/api/sam/reports/metrics
URL link relation n/a
URL query parameters For a list of applicable query parameters, see: Query parameters.
Request headers
Header
Accept-Language (optional)
Values
en-US (only English is supported)

Used to negotiate the language of the response. If this header is not specified, the content is returned in the server language.
Request payload n/a
Request Content-Type
  • 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 this header is not specified, the content is returned in the server language.
Response payload reports element
Response Content-Type
  • Application/json
Normal HTTP response codes
  • 200 – OK
Error HTTP response codes
  • 400 – “Bad Request" if a query parameter contains errors or is missing
  • 401 – “Unauthorized" if the user is not authorized to perform the operation

Message body includes an error message with details.

Query parameters

You can use query parameters to narrow down the results of your search. The following table presents query parameters that you can use for the reports/metrics element.

Table 2. Query parameters for retrieving current license usage reports

The table consists of four columns and nine rows.
Parameter Description Required Value
criteria Filtering criteria, expressed in the following format: 
<connector>:[[<input parameter>,
<operator>,<value>,....]]
For example: 
criteria=and:[[productName,begins_with,WebSphere],
[metrictype,=,3]]
For the list of input parameters, see: Filtering parameters.		 No
enddate The query end date. Yes Date in the YYYY-MM-DD format
format Returns data in JSON format. Yes json
limit The number of rows to be returned. No Numeric Default: 50
offset The number of the first row of data to be returned. No NumericDefault: 0
order[] The parameter can be used to sort the results. The format is:
order[]=<column>+<dir>
where:
  • <column> is the column name
  • <dir> is the direction of the sort. The valid values are asc (ascending) and desc (descending).
For example: 
order[]=product+asc
Restriction: You can specify only one sort parameter.
 No
reportgroupid Identifier of the report group to which the computer that has the software installed belongs. No Numeric Default: 1
startdate The query start date. Yes Date in the YYYY-MM-DD format
token A unique user authentication identifier. Yes Alphanumeric

Filtering parameters

The following table describes extra filtering input parameters. The response output uses the same information items as the input parameters.

Table 3. Input parameters and response output

The table consists of three columns and four rows.
Filtering parameter Description Value
metrictype The type of the metric. The possible values are:
  • 3 - PVU full capacity
  • 4 - PVU subcapacity
  • 7 - RVU full capacity
  • 8 - RVU subcapacity
 Numeric
product The name of the product. String
productid The identifier of the product. Numeric
quantity The quantity of used licenses. This is the license peak value, the maximum value utilized by the product over the specified time period. Numeric

Example command

http://localhost:9988/api/sam/reports/metrics
?token=7adc3efb175e2bc0f4484bdd2efca54a8fa04623&format=json&startdate=2013-01-15
&enddate=2013-04-26

Example HTTP conversation

Request
GET /api/sam/reports/metrics
?token=7adc3efb175e2bc0f4484bdd2efca54a8fa04623&format=json
&startdate=2013-01-15&enddate=2013-04-26 HTTP/1.1
Host: localhost:9080 
Accept: application/json 
Accept-Language: en-US
Response header
HTTP/1.1 200 OK
Content-Type: application/json
Content-Language: en-US
Response body (JSON)
[
{ "product":"IBM WebSphere MQ Advanced",
  "productid":190,
  "isreaggregationneeded":false,
  "rollup_history":[{"time":"2013-11-11T00:00:00Z","hwm":"270"},
  {"time": "2013-11-11T00:00:00Z","hwm":"270"}],
  "metrictype":3,
  "quantity":270}
]