List Performance History

Base URL

https://{SERVER}/api/?apikey={yourAPIkey}&service= list_performance_history

Description

Obtains the data relating to all the Performance and Bandwidth Monitoring Checks running on the specified device.

Data is available for 24 hours at 15 minute intervals and for 8 days at hourly intervals. If data is needed for longer then it will need to be stored; for efficiency use the since parameter to only obtain new data.

Note: The Windows Agent supports the Performance Monitoring Check for workstations.

Parameters

Required parameters

Add required parameters immediately after the base URL.

https://{SERVER}/api/?apikey={yourAPIkey}&service= list_performance_history&required_parameters={parameter-value}

Parameter	Description	Type	Options	Default
deviceid	The deviceid must be a valid id.	integer	0	0

Optional parameters

Add optional parameters immediately after the base URL.

https://{SERVER}/api/?apikey={yourAPIkey}&service= list_performance_history&optional_parameters={parameter-value}

Parameter	Description	Type	Required	Options	Default
describe	Returns a description of the service.	boolean	no	true	0

Determine parameter values

Use the following associated service calls to determine parameter values.

Parameter	Call	URL Format
deviceid	list_devices_at_client	https://`{SERVER}`/api/?apikey=`{yourAPIkey}`&service=list_devices_at_client&clientid=CLIENTID&devicetype=server
	list_servers	https://`{SERVER}`/api/?apikey=`{yourAPIkey}`&service=list_servers&siteid=SITEID
	list_workstations	https://`{SERVER}`/api/?apikey=`{yourAPIkey}`&service=list_workstations&siteid=SITEID
siteid	list_sites	https://`{SERVER}`/api/?apikey=`{yourAPIkey}`&service=list_sites&clientid=CLIENTID
clientid	list_clients	https://`{SERVER}`/api/?apikey=`{yourAPIkey}`&service=list_clients

Examples

List Performance History

https://{SERVER}/api/?apikey={yourAPIkey}&service=list_performance_history&deviceid=DEVICEID&interval=INTERVAL&since=SINCE

Example response

<example>
  <result created="2024-04-05T10:48:40+01:00" host="SERVER" status="OK">
    <bandwidth>
      <host>
        <name>example.com port 12345[Descriptive name of check]</name>
        <host>example.com[IP address or hostname to identify the check]</host>
        <check_id>909090909[id of check]</check_id>
        <receive>2000[threshold rate in whole kB/s]</receive>
        <transmit>2000[threshold rate in whole kB/s]</transmit>
        <history>
          <data>
            <start>2024-09-16 12:00:00[first second of interval]</start>
            <end>2024-09-23 10:59:59[last second of interval, note duration can be more than requested if consecutive intervals have the same values]</end>
            <receive>[actual rate in kB/s e.g. 0.085]</receive>
            <transmit>[actual rate in kB/s e.g. 150.125]</transmit>
          </data>
          [...more data elements...]
        </history>
      </host>
      [...more host elements...]
    </bandwidth>
    <disk_load>
      <disk>
        <disk>0 C: D: E:[identification info for the physical disk]</disk>
        <check_id>909090909[id of check]</check_id>
        <read_queue_length>2[threshold queue length, whole items]</read_queue_length>
        <write_queue_length>2[threshold queue length, whole items]</write_queue_length>
        <average_disk_time>50[threshold disk time percentage]</average_disk_time>
        <history>
          <data>
            <start>2024-09-15 12:00:00[start of interval]</start>
            <end>2024-09-15 12:59:59[end of interval]</end>
            <disk_time_average>0.048[average disk time]</disk_time_average>
            <disk_time_max>2.554[maximum disk time]</disk_time_max>
            <read_queue_average>0[average queue length]</read_queue_average>
            <read_queue_max>0.018[maximum queue length, fractional as instantaneous data not available]</read_queue_max>
            <write_queue_average>0.00025[average queue length]</write_queue_average>
            <write_queue_max>0.026[maximum queue length, fractional as instantaneous data not available]</write_queue_max>
          </data>
          [...more data elements...]
        </history>
      </disk>
      [...more disk elements...]
    </disk_load>
    <cpu_queue>
      <check_id>909090909[id of check]</check_id>
      <average_length>2[threshold queue length; whole number]</average_length>
      <history>
        <data>
          <start>2024-09-15 12:00:00[start of interval]</start>
          <end>2024-09-15 12:59:59[end of interval]</end>
          <queue_average>0.0795[actual average]</queue_average>
          <queue_max>2[actual maximum]</queue_max>
        </data>
        [...more data elements...]
      </history>
    </cpu_queue>
    <cpu_load>
      <check_id>909090909[id of check]</check_id>
      <average_load>70[threshold load percentage]</average_load>
      <history>
        <data>
          <start>2024-09-16 18:00:00</start>
          <end>2024-09-16 18:59:59</end>
          <cpu>[note the list of CPUs is only included if there are 2, 3 or 4, for a single CPU the load_average and load_max will be reported directly in the data element; for more than 4 CPUs the averages across all of them will be reported in the same way as a single CPU system]
            <cpu_id>1[id of CPU, counts from 1, might not match hardware ids; only if more than 1 CPU]</cpu_id>
            <load_average>0.98825[average load]</load_average>
            <load_max>6.875[maximum load over smallest measurable timeframe]</load_max>
          </cpu>
          <cpu>
            <cpu_id>2</cpu_id>
            <load_average>0.27025</load_average>
            <load_max>4.063</load_max>
          </cpu>
          [...more cpu elements...]
        </data>
        [...more data elements...]
      </history>
    </cpu_load>
    <network_usage>
      <interface>
        <adapter>HP NC7782 Gigabit Server Adapter[descriptive name]</adapter>
        <check_id>909090909[id of check]</check_id>
        <average_usage>40[threshold of check, kB/s]</average_usage>
        <history>
          <data>
            <start>2013-09-15 14:00:00[start of interval]</start>
            <end>2013-09-23 10:59:59[end of interval]</end>
            <bandwidth>1250000[maximum bandwidth available]</bandwidth>
            <total_average>0[combined averages of transmit plus receive]</total_average>
            <total_max>0[combined maximums of transmit plus receive]</total_max>
            <transmit_average>0[average transmit throughput]</transmit_average>
            <transmit_max>0[maximum transmit throughput]</transmit_max>
            <receive_average>0[average receive throughput]</receive_average>
            <receive_max>0[maximum receive throughput]</receive_max>
          </data>
          [...more data elements...]
        </history>
      </interface>
      [...more interface elements...]
    </network_usage>
    <memory_usage>
      <check_id>909090909[id of check]</check_id>
      <available_min>10[threshold for minimum available memory, MB]</available_min>
      <average_pages>20[threshold for page usage]</average_pages>
      <average_page_file>70[threshold for paging file]</average_page_file>
      <non_paged_pool>100[threshold for non-paged]</non_paged_pool>
      <average_commit>0[threshold for commit charge]</average_commit>
      <history>
        <data>
          <start>2024-09-15 17:00:00[start of interval]</start>
          <end>2024-09-15 17:59:59[end of interval]</end>
          <available_average>296.5[average memory available, MB]</available_average>
          <available_min>288.5[minimum memory available, MB]</available_min>
          <commit_charge_average>2894.25[average commit charge, MB]</commit_charge_average>
          <commit_charge_max>2900[maximum commit charge, MB]</commit_charge_max>
          <page_faults_average>13[average page faults]</page_faults_average>
          <page_faults_max>303[maximum page faults]</page_faults_max>
          <file_usage_average>44.25[percentage file usage]</file_usage_average>
          <file_usage_max>45[percentage file usage]</file_usage_max>
          <non_paged>63[usage of non-paged memory]</non_paged>
          <total>2047[total physical memory installed which can be used as main memory, MB]</total>
        </data>
      </history>
    </memory_usage>
  </result>
</example>

Returned fields

Bandwidth Monitoring Check

Can contain multiple entries (in XML output these will be host elements), each containing:

Field	Type	Can Be Empty	Description
name	string	no	Descriptive name of the bandwidth check which populated this data
host	string	yes	The hostname or IP address the data is for
check_id	integer	no	The check which populated this data
receive	integer	no	Receive rate threshold (from the check) in kilobytes per second
transmit	integer	no	Transmit rate threshold (from the check) in kilobytes per second
history	list (data elements in XML)	no	Each entry contains: start* - first second of the period for which this data applies; UTC, ISO-8601 end* - last second of the period for which this data applies; UTC, ISO-8601 receive* - float/decimal; average transmission rate (kilobytes per second) transmit* - float/decimal; average transmission rate (kilobytes per second)

Performance Monitoring Check - Physical Disk

Field	Type	Can Be Empty	Description
disk	string	no	ID of the disk, followed by a list of drives on that disk
check_id	integer	no	The check which populated this data
read_queue_length	integer	yes	Current threshold (from the check)
write_queue_length	integer	no	Current threshold (from the check)
average_disk_time	integer	yes	Percentage - current threshold (from the check)
history	list (data elements in XML)	no	Each entry contains: start - first second of the period for which this data applies; UTC, ISO-8601 end* - last second of the period for which this data applies; UTC, ISO-8601 disk_time_average** - float/decimal; average disk time (percentage) for the period disk_time_max* - float/decimal; maximum disk time (percentage) for the period read_queue_average* - float/decimal; average read queue length for the period read_queue_max** - float/decimal; maximum read queue length for the period write_queue_average* - float/decimal; average write queue length for the period write_queue_max* - float/decimal; maximum write queue length for the period

Performance Monitoring Check - Processor Queue Length

Field	Type	Can Be Empty	Description
check_id	integer	no	The check which populated this data
average_length	integer	yes	Current threshold (from the check)
history	list (data elements in XML)	no	Each entry contains: start* - first second of the period for which this data applies; UTC, ISO-8601 end* - last second of the period for which this data applies; UTC, ISO-8601 average* - float/decimal; average queue length for the period max - float/decimal; maximum queue length for the period

receive	integer	no	Receive rate threshold (from the check) in kilobytes per second
transmit	integer	no	Transmit rate threshold (from the check) in kilobytes per second
history	list (data elements in XML)	no	Each entry contains: start* - first second of the period for which this data applies; UTC, ISO-8601 end* - last second of the period for which this data applies; UTC, ISO-8601 receive* - float/decimal; average transmission rate (kilobytes per second) transmit* - float/decimal; average transmission rate (kilobytes per second)

Performance Monitoring Check - Processor Utilization

Field	Type	Can Be Empty	Description
check_id	integer	no	The check which populated this data
average_load	integer	no	Current threshold (from the check)
transmit	integer	no	Transmit rate threshold (from the check) in kilobytes per second
history	list (data elements in XML)	no	Each entry contains: start - first second of the period for which this data applies; UTC, ISO-8601 end* - last second of the period for which this data applies; UTC, ISO-8601 JSON List: XML: cpu elements * 1..4 entries; just an average and maximum if 1 CPU or more than 4 CPUs; separately listed if 2..4 CPUs cpu_id* - integer; 1..4 load_average* - float/decimal; average load for the period load_max* - float/decimal; maximum load for the period.

Performance Monitoring Check - Network Interface Utilization

Can contain multiple entries (in XML output these will be interface elements), each containing:

Field	Type	Can Be Empty	Description
adapter	string	no	Name of the network adapter
check_id	integer	no	The check which populated this data
average_usage	integer	yes	Percentage threshold (from the check)
history	list (data elements in XML)	no	Each entry contains: start** - first second of the period for which this data applies; UTC, ISO-8601 end - last second of the period for which this data applies; UTC, ISO-8601 bandwidth* - integer; maximum bandwidth for this network interface (kilobytes per second) total_average* - float/decimal; average transmission rate (kilobytes per second) total_max* - float/decimal; maximum transmission rate (kilobytes per second) transmit_average* - float/decimal; average transmission rate (kilobytes per second) transmit_max* - float/decimal; maximum transmission rate (kilobytes per second) receive_average* - float/decimal; average transmission rate (kilobytes per second) receive_max* *- float/decimal; maximum transmission rate (kilobytes per second)

Performance Monitoring Check - Memory Usage

Field	Type	Can Be Empty	Description
check_id	integer	no	The check which populated this data
available_min	integer	yes	Threshold (from the check)
average_pages	integer	no	Threshold (from the check)
average_page_file	integer	no	Threshold (from the check)
non_paged_pool	integer	yes	Threshold (from the check)
average_commit	integer	no	Threshold (from the check)
history	list (data elements in XML)	no	Each entry contains: start* - first second of the period for which this data applies; UTC, ISO-8601 end - last second of the period for which this data applies; UTC, ISO-8601 available_average* - float/decimal; average available memory during the period (megabytes) available_min* - float/decimal; minimum available memory during the period (megabytes) commit_charge_average* - float/decimal; average commit charge during the period (megabytes) commit_charge_max* - float/decimal; maximum commit charge during the period (megabytes) page_faults_average* - float/decimal; average page faults per second over the period page_faults_max** - float/decimal; maximum page faults per second over the period file_usage_average - float/decimal; average file usage over the period file_usage_max* - float/decimal; maximum file usage during the period non_paged* - float/decimal; amount of non-paged memory during the period total* *- integer; total installed physical memory (megabytes)

Notes

If the data remains identical for multiple consecutive intervals then it will be returned as one long interval, thus the specified interval is the minimum interval length which will be returned.

Any intervals for which the values are unknown are not included in the output. The ordering of data is not guaranteed; ensure you use the start and end fields when reading the data.

All times are UTC. The interval start and end times are not exact due to the various times at which the agent runs the checks and plus the variable durations for reporting and processing such data.

The newest data available will be the last full interval reported which for servers will be recorded during the next interval but for workstations could be sometime later depending on the frequency at which checks are run.

Hourly data is an average of the four 15 minute intervals with which it aligns. The maximums reported are actually averages over the smallest timeframe the agent can obtain data for.

Data intervals are returned with times marking the first second and last second of the interval; note that no performance data has to-the-second precision.

Thresholds reported alongside the history are the current parameters for the relevant check; previous threshold values are not available even though it's possible they have changed during the reported time frame.

Hardware changes could cause significant changes to the data returned, including the number of CPUs listed which is recorded on a per-interval basis.

If the device has multiple checks of same type configured, then you'll see the thresholds and check_id for the one which most recently reported a result; data for the others will be identical, but there could be additional thresholds being monitored; obtain the list of checks from list_checks if such information is needed.