Download reports with LicenseUsage

The LicenseUsage query returns an overview of peak license usage times, grouped by hour, day, or month. Data is added to this report when at least 90% of your BeyondTrust licenses are in use. You may use any of the following sets of parameters to generate reports:

  • start_date, duration, and group_by
  • start_time, duration, and group_by

The reporting API is an authenticated API. For instructions on using authenticated APIs using OAuth, see Authenticate to the Remote Support API. The API account must have the permission Allow Access to License Usage Reports.

Parameters for LicenseUsage

start_date=[YYYY-MM-DD] Specifies that the report should return peak license usage data beginning on or after this date.
start_time=[timestamp] Specifies that the report should return peak license usage data beginning at or after this time. The time must be a UNIX timestamp (UTC).
duration=[integer] Length of time from the specified date or time for which you wish to pull reports, or 0 to pull from the specified date to present. If start_date is specified, duration represents days; if start_time is specified, duration represents seconds.
group_by Specifies whether the data should be grouped by hour, day, or month.

XML response for LicenseUsage query

<license_usage>

Contains a <license_time_intervals> element. If no license usage data is returned, this element will contain no license usage elements. If an error occurs during the search, it will contain an <error> element describing the problem.

Also contains <start_time> and <end_time> elements displaying the time parameters in the system time and with a timestamp attribute in UTC. A <group_by> element shows whether the data is grouped by hour, day, or month.

Element names and attributes

/license_usage/license_time_intervals
<license_time_interval> Contains a <license_time_interval> element for each time at which peak license usage was logged.
/license_usage/license_time_intervals/license_time_interval
timestamp (attribute) The timestamp at which peak license usage was logged.
datetime (attribute) The date and time at which peak license usage was logged.
<license_count> Contains a <license_count> element for each potential type of license usage. This displays the number of licenses in use at that time.
/license_usage/license_time_intervals/license_time_interval/license_count
license_type (attribute) The type of license used by the representative.
reason (attribute) Can be either login or extended_contact, or this attribute may not be present. The login reason indicates that a license was in use due to a user being logged into the representative console. The extended_contact reason indicates that a license was being consumed due to a user being in extended availability mode. If no reason is listed, the license count is the total number of licenses in use.

Query examples for LicenseUsage

License usage starting October 1 2016 to present, grouped by hour

https://support.example.com/api/reporting?generate_report=LicenseUsage&start_date=2016-10-01&duration=0&group_by=hour

License usage during the month of October 2016, grouped by day

https://support.example.com/api/reporting?generate_report=LicenseUsage&start_date=2016-10-01&duration=31&group_by=day

License usage starting 8:00 AM October 1 2016 to present, grouped by month

https://support.example.com/api/reporting?generate_report=LicenseUsage&start_time=1475308800&duration=0&group_by=month

License usage starting 8:00 AM October 1 2016 to 6:00 PM October 1 2016, grouped by hour

https://support.example.com/api/reporting?generate_report=LicenseUsage&start_time=1475308800&duration=36000&group_by=hour