Page History

The Usage History endpoint delivers license usage metrics specific to the Usage History report, allowing you to monitorLicense Statistics API lets you generate data from the Usage History report. This report shows statistics for license usage , during any period that usage was tracked.

Obtaining information about usage history

...

Anchor
obtain obtain

If you want to retrieve information about usage history for a single feature, we recommend that you use the following URL request templateYou can easily fetch metrics about usage history by sending one of the the following HTTP requests.

GET /api/v1/report/usage-history/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 an appropriate value, as needed

 - possible parameters are as follows:

...

Specifies feature-specific parameters.

...

Specifies granularity of the returned data, which can be one of the following:

• Quarter - 2
• Month - 3
• Week - 4
• Day - 5
• Hour - 6

...

No

...

Specifies the name of the report that will be displayed once the report has been exported to PDF or XLS. 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 XLS types. If provided, it cannot be left empty.

...

Applies filtering license usage data on all fields.

To filter by string column, use the following format: 

[
	{ 
		"type": "string",
		"field": "lud",
		"value": "${value}"
	}
]

To filter by numeric column, use the following format:

[
	{ 
		"type": "numeric", 
		"comparison": "${gt | lt | eq}", 
		"field": "${lumin | lua | lumax | lbmin | lbmax | ldtc | hu | ft}",
		"value": "${value}" 
	}
]

GET /api/v1/report/feature-composite/${fcid}/usage-history/${returnType}?sd=${YYYY-MM-DD}&ed=${YYYY-MM-DD}&granularity=${granularity}$(additional parameters, as needed)

GET /api/v1/report/feature-comparison/${ucompi}/report/${returnType}?sd=${YYYY-MM-DD}&ed=${YYYY-MM-DD}&granularity=${granularity}

...

{ 
	"lud": "1", 
	"lumin": "1", 
	"lua": "1", 
	"lumax": "1", 
	"lbmin": "1", 
	"lbmax": "1", 
	"ldtc": "1", 
	"hu": "1", 
	"ft": "1"
}

...

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

...

If your request is successful, you should see a response similar to the following:

{
	"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}
}

where the response fields can be explained as follows:

...

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.

...

Obtaining information about usage history comparison for features

If you want to obtain information about usage history comparison for features, we recommend that you use the following URL request template.

GET /api/v1/report/license-server/${lsid}/usage-history/comparison/json?fi=${featureIdsreturnType}&?sd=${startDate}&ed=${endDate}&granularity=${granularity}

Possible parameters are as follows:

...

YYYY-MM-DD

...

}&ed={YYYY-MM-DD

...

}&granularity=${granularity}$(additional parameters, as needed)

...

• Quarter - 2
• Month - 3
• Week - 4
• Day - 5
• Hour - 6

Currently the report is only returned only in JSON syntax. There are plans to introduce CSV, XLS and PDF formats in the future.

If your request is successful, you should see a response similar to the following:

{
	"success": ${success},
  	"msg": ${message},
  	"data": [
    	{
      		"fid": ${featureId_1},
      		"lud": ${date},
      		"lumin": ${minUsed},
      		"lua": ${averageUsed},
      		"lumax": ${maxUsed},
      		"lbmin": ${minBorrowed},
      		"lbmax": ${maxBorrowed},
      		"ldtc": ${denials},
      		"hu": ${hoursUsed},
      		"ft": ${total}
    	},
		{
      		"fid": ${featureId_2},
      		"lud": ${date},
      		"lumin": ${minUsed},
      		"lua": ${averageUsed},
      		"lumax": ${maxUsed},
      		"lbmin": ${minBorrowed},
      		"lbmax": ${maxBorrowed},
      		"ldtc": ${denials},
      		"hu": ${hoursUsed},
      		"ft": ${total}
    	}
  	],
  	"code": ${code},
  	"totalCount": ${count}
}

where the fields have the same values as the ones explained in Obtaining information about usage history for feature, above.

Obtaining information about usage history for license server

If you want to obtain information about usage history for all visible features for a given server, we recommend that you use the following URL request template.

GET /api/v1/report/usage-history/license-server-group/${lsidlsgid}/usage-history/${returnType}?sd=${startDateYYYY-MM-DD}&ed={endDateYYYY-MM-DD}&granularity=${granularity}$(additional parameters, as needed)

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.

[
	{ 
		"type": "string", 
		"field": "${lud | fns | fv | ftype}",
		"value": "${value}"
	}
]

[
	{ 
		"type": "numeric", 
		"field": "${lumin | lua | lumax | lbmin | lbmax | ldtc | hu | ft}",
		"value": "${value}"
	}
]

{ 
	"lud": "1", 
	"lumin": "1", 
	"lua": "0", 
	"lumax": "1", 
	"lbmin": "1", 
	"lbmax": "1", 
	"ldtc": "1", 
	"hu": "0", 
	"ft": "0",
	"fns": "1",
	"fv": "1",
	"ftype": "1"
}

lud | fns | fv | ftype | fid | lumin | lua | lumax | lbmin | lbmax | ldtc | hu | ft

If your request is successful, you should see a response similar to the following:

{
	"success": ${success},
	"msg": ${message},
  	"data": [
    	{
      		"fid": ${featureId_1},
      		"lud": ${date},
      		"lumin": ${minUsed},
      		"lua": ${averageUsed},
      		"lumax": ${maxUsed},
      		"lbmin": ${minBorrowed},
      		"lbmax": ${maxBorrowed},
      		"ldtc": ${denials},
      		"hu": ${hoursUsed},
      		"ft": ${total},
			"fns": ${featureName},
			"ftype": ${featureType},
			"fv": ${featureVersion}
    	},
		{
      		"fid": ${featureId_1},
      		"lud": ${date},
      		"lumin": ${minUsed},
      		"lua": ${averageUsed},
      		"lumax": ${maxUsed},
      		"lbmin": ${minBorrowed},
      		"lbmax": ${maxBorrowed},
      		"ldtc": ${denials},
      		"hu": ${hoursUsed},
      		"ft": ${total},
			"fns": ${featureName},
			"ftype": ${featureType},
			"fv": ${featureVersion}
    	}
  	],
  	"code": ${code},
  	"totalCount": ${count}
}

where the response fields can be explained as follows:

...

ldtc

...

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

...

.