The User Hosts List endpoint delivers license usage metrics specific to the Realtime Users Count report, namely "User history for last 14 days"; that is, a list of all user on host pairs using a license on all realtime servers over a given time frame.
Obtaining information about user hosts
You can easily list user on host pairs by sending the following HTTP request.
GET /api/v1/report/features/user-history/user-hosts/${returnType}?sd=${startDate}&ed=${endDate}&(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 |
returnType | Yes | string | Specifies the format in which license usage data will be returned. The format can be one of the following: json, csv, xlsx, or pdf. |
sd | Yes | string | Specifies the start date for which the report will be generated.The date is in YYYY-MM-DD format; for example, 2017-05-20. |
ed | Yes | string | Specifies the end date for which the report will be generated. The date is in YYYY-MM-DD format; for example, 2017-05-27. |
rn | No | string | 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. |
filter | No | json/string | Applies filtering license usage data on all fields. To filter by a string column, use the following format:
[ { "type": "string", "field": "${ un | hn }", "value": "${value}" } ] |
fieldsVisibility | No | json/string | Specifies field visibility settings, like this:
{ "uid": "1", "un": "1", "hn": "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. |
limit | No | integer | Determines the maximum number of data records that can be returned. The value must be greater than zero. |
offset | No | integer | Specifies the offset of the first row to return. |
orderBy | No | string | Specifies the field by which you want to order your data records. The field name can be one of the following: uid | un | hn (See this section for more field-specific information.) If orderBy is provided, orderDirection is mandatory. |
orderDirection | No | string | Determines whether the sorting results will be displayed in ascending (ASC) or descending (DESC) order. If orderDirection is provided, orderBy is mandatory. |
Response
The following code block shows an example result of a successful request.
{ success: ${success}, msg: ${message}, data: [{ "uid": ${userId}, "un": ${userName}, "hn": ${hostName}, "uil": ${userIsLdap} }], "code": ${errorCode}, "totalCount": ${totalNumberOfRecords} }
where the response fields can be explained as follows:
Field | Type | Description |
uid | integer | User ID. |
un | string | Username. |
hn | string | Hostname. |
uil | boolean | Indicates whether user details have been imported from an LDAP directory. Note that you cannot filter and order data by this field. |
msg | string | Error message returned on failure. |
success | boolean | Indicates whether your API request was successfully processed. |
code | integer | Error code for unsuccessful request. |
totalCount | integer | Total number of all matching results. |
Example
The following example shows a command that downloads data in CSV format about user on host pairs that were using licenses for 2017-01-01 through 2017-01-14.
curl -H "X-Auth-token: token" "http://yourdomain/api/v1/report/features/user-history/user-hosts/csv?sd=2017-01-01&ed=2017-01-14"