The Feature Utilization endpoint delivers license usage metrics specific to Utilization History, allowing you to monitor the percentage of license usage during any period that usage was tracked.
Obtaining information about utilization history
You can easily fetch metrics about the percentage of license usage over a given time period by sending the following HTTP request.
GET /api/v1/report/feature/${featureId}/utilization-history/${returnType}?sd=${YYYY-MM-DD}&ed=${YYYY-MM-DD}&st=${HH:MM}&et=${HH:MM}&incd=${true_or_false}(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.
| Parameter | Required | Type | Description |
|---|---|---|---|
| ${featureId} | Yes | integer | Internal License Statistics identification of the feature for which you want to view utilization history. |
| ${returnType} | Yes | string | Standard format option. See Making an API request for details. |
| sd | Yes | date | Start date for which you want to generate the report. |
| ed | Yes | date | End date for which you want to generate the report. The date is inclusive, meaning that all data from a particular day will be included in the report. |
| st | Yes | time | Start time of the time window to be applied for each date in a range ("working hours"). |
| et | Yes | time | End time of the time window to be applied for each date in a range ("working hours"). |
| incd | No | boolean | Specifies how utilization value should be calculated; i.e., whether the downtime periods should be included. If true, the length of the entire range will be used as a denominator [(days between ${sd} and ${ed} inclusively)*(et-st)]. Otherwise, only uptime periods will be used. Defaults to false. |
| standard report options | No | various | See Making an API request for details. |
Response
On success, report will contain one row for each usage level that occurred in specified time range. That is, if maximum usage for feature was 6, report will include 6 records: one for each number between 1 and 6.
Each row consists of the following columns.
| Column | Full name | Type | Description | Visible by default in export |
|---|---|---|---|---|
lc | Licenses In Use | integer | Usage level that other fields are referring to. |  Yes |
lhu | Hours Used | float | Number of hours when at least ${lc} licenses were used. | Yes |
lutil | Utilization | float | Percentage share of time when at least ${lc} licenses where used in percent. Value of ${lhu} is numerator. Denominator value is affected by ${incd} value. | Yes |
Note that the order in the table is the default order of the columns in the exported file.
Example
The following example shows a command that lets you obtain statistics about utilization history for feature "3" over a specific time period, with users' working hours between 9:00 a.m. and 5:00 p.m.
curl --data "sd=2015-01-01" --data "ed=2015-01-02" --data "st=09:00" --data "et=17:00" -H "X-Auth-token: token" "http://yourdomain/api/v1/report/feature/3/utilization-history/json"