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"