...
The Usage History endpoint delivers license usage metrics specific to the Usage History report, allowing you to monitor statistics for license usage during any period that usage was tracked.
Obtaining information about usage history
...
Anchor obtain obtain
obtain | |
obtain |
You can easily fetch metrics about usage history for a single feature by sending by sending one of the the following HTTP requestrequests.
Code Block | ||||||
---|---|---|---|---|---|---|
| ||||||
GET /api/v1/report/feature/${featureId}/usage-history/${returnType}?sd=${startDateYYYY-MM-DD}&ed=${endDateYYYY-MM-DD}&granularity=${granularity}$(additional parameters, as needed) |
where $ indicates a variable value that you can replace with a value that best suits your needs. The possible parameters are described below.
...
Specifies feature-specific parameters.
...
Specifies granularity of the returned data, which can be one of the following:
- QUARTER or 2
- MONTH or 3
- WEEK or 4
- DAY or 5
- HOUR or 6
...
No
...
Specifies the name of the report that will be displayed once the report has been exported to PDF or XLSX. For CSV and JSON formats this parameter will be ignored.
If you don't pass this parameter, it will be generated automatically for PDF and XLSX types. If provided, it cannot be left empty.
...
Applies filtering license usage data on all fields.
To filter by a string column, use the following format.
Code Block | ||||
---|---|---|---|---|
| ||||
[
{
"type": "string",
"field": "lud",
"value": "${value}"
}
] |
To filter by a numeric column, use the following format.
Code Block | ||||
---|---|---|---|---|
| ||||
[
{
"type": "numeric",
"comparison": "${gt | lt | eq}",
"field": "${lumin | lua | lumax | lbmin | lbmax | ldtc | hu | ft}",
"value": "${value}"
}
] |
...
Code Block | ||||||
---|---|---|---|---|---|---|
| ||||||
GET /api/v1/report/feature-composite/${fcid}/usage-history/${returnType}?sd=${YYYY-MM-DD}&ed=${YYYY-MM-DD}&granularity=${granularity}$(additional parameters, as needed) |
Anchor | ||||
---|---|---|---|---|
|
...
Code Block | ||
---|---|---|
|
...
{
"lud": "1",
"lumin": "1",
"lua": "1",
"lumax": "1",
"lbmin": "1",
"lbmax": "1",
"ldtc": "1",
"hu": "1",
"ft": "1"
}
where "1" indicates that a specific field is visible and ''0" indicates that it is not.
Note that the order of the settings you make is important – when exported, the fields will be visible in exactly the same order you specify here.
|
...
Specifies the field by which you want to order your data records. The field name can be one of the following:
lud | lumin | lua | lumax | lbmin | lbmax | ldtc | hu | ft
(See this section for more field-specific information.)
...
Response
The following code block shows an example result of a successful request.
Code Block | ||||
---|---|---|---|---|
| ||||
{
"success": ${success},
"msg": ${message},
"data": [
{
"fid": ${featureId},
"lud": ${date},
"lumin": ${minUsed},
"lua": ${averageUsed},
"lumax": ${maxUsed},
"lbmin": ${minBorrowed},
"lbmax": ${maxBorrowed},
"ldtc": ${denials},
"hu": ${hoursUsed},
"ft": ${total}
}
],
"code": ${code},
"totalCount": ${count}
} |
...
Indicates period of time for which usage information is generated, i.e. date and time for hourly usage and dates for the remaining granularity options.
...
ldtc
...
Error code if success equals false, null otherwise.
...
You can easily fetch metrics about usage history comparison for features by sending the following HTTP request.
Code Block | ||||
---|---|---|---|---|
| ||||
GET /api/v1/report/feature-comparison/${ucompi}/report/${returnType}?sd=${startDateYYYY-MM-DD}&ed=${endDateYYYY-MM-DD}&granularity=${granularity} |
where the possible parameters are as follows:
...
Specifies granularity of the returned data, which can be one of the following:
- QUARTER or 2
- MONTH or 3
- WEEK or 4
- DAY or 5
- HOUR or 6
Code Block | ||||||
---|---|---|---|---|---|---|
| ||||||
GET /api/v1/report/license-server/${lsid}/usage-history/${returnType}?sd=${YYYY-MM-DD}&ed={YYYY-MM-DD}&granularity=${granularity}$(additional parameters, as needed) |
Code Block | ||
---|---|---|
|
Response
The following code block shows an example result of a successful request.
Code Block | ||||
---|---|---|---|---|
| ||||
{
"success": ${success},
"msg": ${message},
"data": [
{
"fid": ${featureId_1},
"fns": ${featureName},
"ftype": ${featureType},
"fv": ${featureVersion},
"lud": ${date},
"lumin": ${minUsed},
"lua": ${averageUsed},
"lumax": ${maxUsed},
"lbmin": ${minBorrowed},
"lbmax": ${maxBorrowed},
"ldtc": ${denials},
"hu": ${hoursUsed},
"ft": ${total}
},
{
"fid": ${featureId_2},
"fns": ${featureName},
"ftype": ${featureType},
"fv": ${featureVersion},
"lud": ${date},
"lumin": ${minUsed},
"lua": ${averageUsed},
"lumax": ${maxUsed},
"lbmin": ${minBorrowed},
"lbmax": ${maxBorrowed},
"ldtc": ${denials},
"hu": ${hoursUsed},
"ft": ${total}
}
],
"code": ${code},
"totalCount": ${count}
} |
...
Feature ID.
...
Indicates period of time for which usage information is generated; i.e., date and time for hourly usage and dates for the remaining granularity options.
...
ldtc
...
Error code if success equals false, null otherwise.
...
You can easily fetch metrics about usage history for a given server by calling this HTTP request:
Code Block | ||||
---|---|---|---|---|
| ||||
GET /api/v1/report/license-server-group/${lsidlsgid}/usage-history/${returnType}?sd=${startDateYYYY-MM-DD}&ed={endDateYYYY-MM-DD}&granularity=${granularity}$(additional parameters, as needed) | ||||
Code Block | ||||
language | js||||
firstline | 1 |
where the possible parameters are as follows:where $ indicates a variable value that you can replace with a value that best suits your needs. The possible parameters are described below.
Parameter | Required | Type | Description |
---|---|---|---|
${ |
featureId} | Yes | integer |
Internal License Statistics identification of the feature to show usage history for. |
${ |
fcid} | Yes |
Specifies granularity of the returned data, which can be one of the following:
- QUARTER or 2
- MONTH or 3
- WEEK or 4
- DAY or 5
- HOUR or 6
If you don't pass this parameter, it will be generated automatically for PDF and XLSX types. If provided, it cannot be left empty.
Applies filtering license usage data on all fields.
To filter by a string column, use the following format.
Code Block | ||||
---|---|---|---|---|
| ||||
[
{
"type": "string",
"field": "${lud | fns | fv | ftype}",
"value": "${value}"
}
] |
To filter by a numeric column, use the following format.
Code Block | ||||
---|---|---|---|---|
| ||||
[
{
"type": "numeric",
"field": "${lumin | lua | lumax | lbmin | lbmax | ldtc | hu | ft}",
"value": "${value}"
}
] |
Specifies field visibility settings, for example:
Code Block | ||
---|---|---|
| ||
{
"lud": "1",
"lumin": "1",
"lua": "0",
"lumax": "1",
"lbmin": "1",
"lbmax": "1",
"ldtc": "1",
"hu": "0",
"ft": "0",
"fns": "1",
"fv": "1",
"ftype": "1"
} |
where "1" indicates that a specific field is visible, and ''0" indicates it is not.
Note that the order of the settings you make is important – when exported, the fields will be visible in exactly the same order you specify here.
Specifies the field by which you want to order your data records. The field name can be one of the following:
lud | fns | fv | ftype | fid | lumin | lua | lumax | lbmin | lbmax | ldtc | hu | ft
(See this section for more field-specific information.)
Response
The following code block shows an example result of a successful request.
Code Block | ||||
---|---|---|---|---|
| ||||
{
"success": ${success},
"msg": ${message},
"data": [
{
"fid": ${featureId_1},
"fns": ${featureName},
"ftype": ${featureType},
"fv": ${featureVersion},
"lud": ${date},
"lumin": ${minUsed},
"lua": ${averageUsed},
"lumax": ${maxUsed},
"lbmin": ${minBorrowed},
"lbmax": ${maxBorrowed},
"ldtc": ${denials},
"hu": ${hoursUsed},
"ft": ${total}
},
{
"fid": ${featureId_1},
"fns": ${featureName},
"ftype": ${featureType},
"fv": ${featureVersion}
"lud": ${date},
"lumin": ${minUsed},
"lua": ${averageUsed},
"lumax": ${maxUsed},
"lbmin": ${minBorrowed},
"lbmax": ${maxBorrowed},
"ldtc": ${denials},
"hu": ${hoursUsed},
"ft": ${total}
}
],
"code": ${code},
"totalCount": ${count}
} |
...
Feature ID.
...
ldtc
...
integer | Internal License Statistics identification of the feature composite to show usage history for. | ||
${ucompi} | Yes | integer | Internal License Statistics identification of feature history comparison. |
${lsid} | Yes | integer | Internal License Statistics identification of the license server to show usage history for. |
${lsgid} | Yes | integer | Internal License Statistics identification of the license server group to show usage history for. |
${returnType} | Yes | string | Standard format option. See Making an API request for details. |
sd | Yes | date | Start date for which the report will be generated. |
ed | Yes | date | End date for which the report will be generated. |
granularity | Yes | enumeration | Period type the result is aggregated for. See granularity descriptions for further details. |
standard report options | No | various | See Making an API request for details. |
Response
On success, this report will contain one row for every feature and every period in which the feature was monitored. Each row consists of the following columns.
Column | Full name | Type | Description | Visible by default in export |
---|---|---|---|---|
lud | Date | string | The time period. Format depends on granularity. | Yes |
fid | Feature Id | integer | Internal License Statistics identification of the feature | No |
fns | Feature Name | string | Feature name. | Visible for all, but feature |
fv | Feature Version | string | Feature version. | Visible for all, but feature |
ftype | Feature Type | enumeration | See feature type descriptions for details. | Visible for all, but feature |
lumin | Min Used | integer | Minimal number of licenses of the feature used in the period. | Yes |
lua | Avg Used | float | Average number of licenses of the feature used in the period. | Yes |
lumax | Max Used | integer | Maximum number of licenses of the feature used in the period. | Yes |
lbmin | Min Borrowed | integer | Minimal number of licenses of the feature borrowed in the period. | Yes |
lbmax | Max Borrowed | integer | Maximum number of licenses of the feature borrowed in the period. | Yes |
ft | Total | integer | Total number of licenses of the feature available in period. | Yes |
hu | Hours Used | float | Cumulative time used by all licenses of the feature in the period, in hours. | Yes |
ldtc | Denials | integer | Number of denials of check out of a license of the feature in the period. | Yes |
Note that the order in the table is the default order of the columns in the exported file for the license server and license server group reports. For feature, feature composite and comparison default order is: fn, fns, fv, lud, lumin, lua, lumax, lbmin, lbmax, ft, hu, ldtc
If any of the requests has invalid or missing parameters, HTTP 400 BAD REQUEST is returned.
...
You can easily fetch metrics for all features on a given license server group by sending the following HTTP request.
Code Block |
---|
GET /api/v1/report/license-server-group/${lsgid}/usage-history/${returnType}?sd=${startDate}&ed={endDate}&granularity=${granularity}$(additional parameters, as needed) |
where $ indicates a variable value that you can replace with a value that best suits your needs. The possible parameters are described below.
...
.