License usage

Query the installed license types and their usage.

Installed licenses report

Query the license types installed on your space and their current usage.

Request

GET .../api/shared_spaces/<space_id>/tenant_licenses

Response

"total_count": 14,
"data": [{
	"type": "license",
	"id": "1001",
	"license_id": "123101",
	"expiration_date": "2024-08-31T23:59:59Z",
	"start_date": "2024-06-20T00:00:00Z",
	"editions": "ENTERPRISE",
	"consumed": 1,
	"license_model": "Concurrent",
	"license_type": "Functional Test Execution Concurrent Runs",
	"license_type_logical_name": "license_type.ft.cc.runs",
	"capacity": 2
},{
	"type": "license",
	"id": "1002",
	"license_id": "118102",
	"expiration_date": "2030-12-31T23:59:59Z",
	"start_date": "2024-06-02T00:00:00Z",
	"editions": "ENTERPRISE",
	"consumed": 6,
	"license_model": "Named",
	"license_type": "VSM Quality Named",
	"license_type_logical_name": "license_type.team.quality.named.users",
	"capacity": 10
},{
	"type": "license",
	"id": "1003",
	"license_id": "120103",
	"expiration_date": "2030-12-31T23:59:59Z",
	"start_date": "2024-06-06T00:00:00Z",
	"editions": "ENTERPRISE",
	"consumed": 16,
	"license_model": "Named",
	"license_type": "ValueEdge Aviator Add-On",
	"license_type_logical_name": "license_type.aviator.named.users",
	"capacity": 20
},{
	"type": "license",
	"id": "1004",
	"license_id": "118103",
	"expiration_date": "2030-12-31T23:59:59Z",
	"start_date": "2024-06-02T00:00:00Z",
	"editions": "ENTERPRISE",
	"consumed": 126,
	"license_model": "Concurrent",
	"license_type": "VSM Quality Concurrent",
	"license_type_logical_name": "license_type.vsm.quality.cc.users",
	"capacity": 200
}]

The consumed attribute means the following:

Concurrent licenses: The amount of licenses currently in use.
Named licenses: The amount of licenses allocated to active users, regardless of whether they are currently logged in.

Peak license usage (technical preview)

The license_usage resource enables you to query the peak periodic usage of concurrent licenses.

Syntax

GET .../api/shared_spaces/<space_id>/license_usage?<parameters>

Note: Use the ALM-OCTANE-TECH-PREVIEW=true header key.

Legacy and new formats

The new report format groups peak usage by license type. The legacy format reports non-grouped overall peak usage. For backward compatibility, the legacy format is used by default.

Note: The default will change to the new format in a future release.

To use the new format, you can either set a configuration parameter, or include an attribute in each request.

Configuration parameter: Set the LICENSE_USAGE_REPORT_IN_LEGACY_FORMAT parameter to false. For details, see Configuration parameters.
Request attribute: Add the new_format=true parameter to the request. For details, see Parameters.

Note: The new_format request parameter overrides the configuration parameter's definition.

Parameters

The following parameters can be used to filter the results:

Parameter	Description
start_date	The start date of the reporting period (YYYY-MM-DD). Example: start_date=2024-09-07 If no start date is given, the report begins 3 days before the present.
end_date	The end date of the reporting period (YYYY-MM-DD). Example: end_date=2024-10-09 If no end date is given, the report ends at the present date.
time_unit	Determines the time interval between the data points in the report. Possible values: days, weeks, months Default: days
new_format	Use to override the LICENSE_USAGE_REPORT_IN_LEGACY_FORMAT configuration parameter. Type: boolean
license_type	Relevant for the new report format. The license type or types to filter by. Use the license logical name. Filter by single license type: license_type="license_type.vsm.quality.cc.users" Filter by multiple license types: query="(license_type IN 'license_type.ent.cc.users','license_type.vsm.quality.cc.users','license_type.ultimate.cc.users')"

Request

GET /api/shared_spaces/1001/license_usage?start_date=2024-10-30&end_date=2024-10-31

Response (new report)

Copy code

{
  "license_usage": [
    {
      "license_type_display_name": "VSM Quality Concurrent",
      "license_type_logical_name": "license_type.vsm.quality.cc.users",
      "usage_peaks": [
        {
          "point": "2024-10-30T00:00:00Z",
          "max_peak": 131
        },
        {
          "point": "2024-10-31T00:00:00Z",
          "max_peak": 122
        }
      ]
    },
    {
      "license_type_display_name": "ValueEdge Ultimate Evaluation Concurrent",
      "license_type_logical_name": "license_type.ultimate.cc.users",
      "usage_peaks": [
        {
          "point": "2024-10-30T00:00:00Z",
          "max_peak": 98
        },
        {
          "point": "2024-10-31T00:00:00Z",
          "max_peak": 104
        }
      ]
    },
    {
      "license_type_display_name": "ALL CONCURRENT",
      "license_type_logical_name": "license_type.aggregated.cc.all",
      "usage_peaks": [
        {
          "point": "2024-10-30T00:00:00Z",
          "max_peak": 150
        },
        {
          "point": "2024-10-31T00:00:00Z",
          "max_peak": 143
        }
      ]
    }
  ],
  "start_date": "2024-10-30",
  "end_date": "2024-10-31",
  "space_id": 1001,
  "time_unit": "Days"
}

Note: The All Concurrent data represents the peak concurrent usage of across all license types. The All Concurrent max peak will almost never equal the sum of the individual license type peaks, that would usually have occurred at different times.

Response (old report)

Copy code

{
    "license_usage": {
        "2024-10-30:00:00.000+0000": 150,
        "2024-10-31:00:00.000+0000": 143
        }
    "space_id":1001,
    "start_date": "2024-10-7",
    "end_date": "2024-10-13",
}