Reporting API

Overview

Highlight’s Service Assurance Platform is a trusted source of real-time and historical data on the network of thousands of companies. These organisations depend on their service provider to manage their network in a transparent way, and a critical element of full transparency includes the creation of historical reports to assess and critique past performance and agree action plans. These service management reports can take a long time to compile as the statistics need to be exported from Highlight and other systems and imported into a document or analytics system for presentation. Highlight has created a Reporting API feature to dramatically shorten the time needed to generate reports, giving the service manager or IT manager time to action the findings of the report, rather than the compilation.

The Reporting API makes it possible to view Highlight’s historic, summarised data outside the Highlight Service Assurance Platform. After the initial set-up which creates an API key on a specific folder, you can download monthly or daily data for all connectivity services including Broadband and Cellular. This will show, for example, the total availability of a line for a given period. The data can be displayed in Excel, Power BI or another analytics tool. If needed, Highlight data can be combined with data from other sources like an IT service management system.

Who benefits?

Service managers, account managers, product managers and IT managers

The Highlight Reporting API can significantly reduce the amount of time spent on compiling data to produce monthly service reports. Instead of taking days to produce a single customer report, automatic syncing of the Highlight data into your analytics report enables all your customers report data to be accurate and up-to-date in minutes. This has several benefits:

More time to focus on what the data indicates and what actions can improve performance
Report data can be updated in minutes, making the report current and accurate
The option to offer service management to a wider selection of enterprise customers with the same number of service managers

Thus, the Reporting API benefits both service providers and their enterprise customers.

Get in touch
Highlight offers professional services for initial setup of the Reporting API and templates for interactive reports in Excel and Power BI. Contact us for assistance in setup and interpretation the API data or for a copy of our ready-to-use templates.

Partner Domain Setup

A ReportingApiKey value is set by Highlight Support upon request from a partner and associated with a folder in the partner's Highlight tree. The key denotes the scope that the Reporting API operates within, meaning the API can access historic summarised reporting data for all watches in the associated folder and any subfolders.

The Returned Data from the API

The API supports these functions:

The watch tree details as a WatchNodeDto
The option to limit the data returned by using a list of folders
The summarised daily or monthly data in these Dtos:
- Bearer Summary, including:
  - Availability Summary
  - Load Summary
  - Health Summary
- Broadband Summary and Cellular Summary
- Tunnel Summary
- Performance Test Summary
- Wireless Access Point Summary
Inventory Data

Highlight has partitioned the data to enable flexibility for partners so that a partner can decide what reporting data they wish to extract and not be overburdened with excess data.

Watch Nodes

Get Tree Data

Obtain the “Watch Details” data as defined in the Highlight tree. Using the v2 URL means all watch types are returned.

HTTP Header:

x-api-key: The reporting api key (supplied by Highlight Support)

URL: https://reportingapi.highlighter.net/api/v2/tree/watch

HTTP Response:

200 – OK: A successful request. A JSON array of WatchNode will be returned
400 – Bad Request: The reporting API key is invalid or not provided. A message will be returned
One or more of the folderIds are not valid (do not reside under the ReportingApi key or does not exist)

Http Query String Optional Parameter

folderIds: Integer - Optional list of folder or location IDs to limit the data returned and improve speed. Default: Empty (no limit, returns data from all child folders)

WatchNodeDto:

Refer to edit watch for more details on these fields.

Property	Type	Description
watchId	int	The Highlight unique identifier of the watch
name	string	The name of the watch as defined in the ‘Edit Watch’ dialog
description	string	The description of the watch as defined in the ‘Edit Watch’ dialog
locationId	int	The Highlight identifier of the location of the watch
location	string	The name of the location the watch is under
path	string	The folder path of the watch, starting from the first subfolder of the reporting API key folder
productType	string	The product type of the watch as defined in the ‘Edit Watch’ dialog, ‘Bearer’ if empty
customerReference	string	The customer reference of the folder
visibility	string	“Internal” \| “Customer”. The visibility value of the watch as defined in the ‘Edit Watch’ dialog. Both are delivered if nothing is defined.
reference	string	The reference of the watch as defined in the ‘Edit Watch’ dialog
accessIn	long?	If ADSL circuit, then represents the Bandwidth In, otherwise it is the Bearer Speed (measured in bits)
accessOut	long?	If ADSL circuit, then represents the Bandwidth In, otherwise it is the Bearer Speed (measured in bits)
tierIn	long?	For Dedicated Access and SDSL circuits it represents the Bandwidth. For ADSL it is not used (measured in bits)
tierOut	long?	For Dedicated Access and SDSL circuits it represents the Bandwidth. For ADSL it is not used (measured in bits)
parentWatchId	int?	The Highlight unique identifier of the associated parent watch, null if there is no parent watch (not in v1)
parentWatchName	string	The name of the associated parent watch, empty string if there is no parent watch (not in v1)
watchType	string	The constant value which represents the type of watch. Values are: (not in v1) ADSL SDSL Bearer VLAN Multilink Traffic Class Tunnel Wireless Access Point Cellular Nbar Flow LAN Switch HTTP Server ICMP Echo MOS Test Precision Delay TCP Connect UDP Echo
watchNodeVpnTunnel	WatchNodeVpnTunnelDto	VPN Tunnel data, null if not a tunnel watch.
performanceWatch	PerformanceWatchDto	Performance Watch data, null if not a performance test watch.
wapWatch	WapDto	Wireless Access Point specific data, null if not a wireless access point watch.
apiName	string	API name from the tree

WatchNodeVpnTunnelDto:

Property	Type	Description
details	string	The source location and destination location of the tunnel
parentDeviceName	string	The parent "From" device associated with the tunnel. This shows the description if available, otherwise the name.
destination	string	The destination location of the tunnel. If destination name is not present, null is returned.

PerformanceWatchDto:

Property	Type	Description
deviceAddress	string	If parent is a tunnel, then the value is null. If the parent is not a tunnel, then the performance test's associated device's DeviceAddress value
sourceDevice	string	If parent is a tunnel, then From/Source address plus the device name. If parent is not a tunnel, then From/Source description if available or address
destinationDevice	string	If parent is a tunnel, then To/Target address plus the device name. If parent is not a tunnel, then To/Target description if available or address

WapDto:

Property	Type	Description
Location	string	The WAP Location data is available from some vendors and may have been configured on the WiFi controller.
Name	string	The WAP Name as configured on the WiFi controller.
Serial	string	The serial number of the WAP if available from the WiFi controller.
WapType	string	The ‘Device Type’ taken from the WAP, eg ‘Cisco 5505 WAP’.
Details	string	This is either the parent endpoint 'Name' (Controller watches) or the 'WAP Name' (classic WiFi watches).

Example Returned JSON:

❴ "watchId": 489246, "name": "L_429956960589682040_to_L_113197070097781636_489245", "description": "France - Paris - Europe To UK - London", "locationId": 489244, "location": "France - Paris - Europe", "path": "KFV Services >> Regional Offices >> Europe", "productType": "", "customerReference": "", "visibility": "Customer", "reference": "", "accessIn": 1000000000, "accessOut": 1000000000, "tierIn": 0, "tierOut": 0, "parentWatchId": null, "parentWatchName": "", "watchType": "Tunnel", "watchNodeVpnTunnel": ❴ "details": "France - Paris - Europe To UK - London", "parentDeviceName": "Paris Primary MX" "destination": "UK - London" ❵ "performanceWatch": null, "wapWatch": null, "apiName": null, ❵

❴ "watchId": 49377, "name": "PI_49375_49377", "description": "", "locationId": 49078, "location": "Singapore", "path": "KFV Services >> Regional Offices >> AsiaPac", "productType": "", "customerReference": "", "visibility": "Customer", "reference": "", "accessIn": null, "accessOut": null, "tierIn": null, "tierOut": null, "parentWatchId": 49375, "parentWatchName": "Singapore_router", "watchType": "MOS Test", "watchNodeVpnTunnel": null, "performanceWatch": ❴ "deviceAddress": "192.168.102.11", "sourceDevice": "Singapore", "destinationDevice": "Sydney" ❵ "wapWatch": null, "apiName": null, ❵

❴ "watchId": 2985367, "name": "WAP_2985357_5C838F352E70", "description": "aironet1", "locationId": 2985356, "location": "London", "path": "KFV Services", "productType": "", "customerReference": "", "visibility": "Customer", "reference": "", "accessIn": 54000000, "accessOut": 54000000, "tierIn": 54000000, "tierOut": 54000000, "parentWatchId": null, "parentWatchName": "", "watchType": "Wireless Access Point", "watchNodeVpnTunnel": null, "performanceWatch": null, "wapWatch": ❴ "location": "Dev/Sales", "name": "aironet1", "type": "AIR-CAP1702I-E-K9" "serialNumber": "FGL1931XFX5", "details": "access point for dev/sales", ❵ "apiName": null, ❵

Limit by child folders

To improve the speed of API calls for large estates, it's possible to limit the data returned by using a list of folders in the API query. First step is to obtain a list of the child folders under the folder represented by the given ReportingApi key.

This is optional. If no folder IDs are provided, then data for all child folders is returned.

Get Child Folders

Obtain the child folders under the folder represented by the given ReportingApi key.

HTTP Header:

x-api-key: The reporting api key (supplied by Highlight Support)

URL: https://reportingapi.highlighter.net/api/v2/tree/folders

HTTP Response:

200 – OK: A successful request. A JSON array of folders will be returned
400 – Bad Request: The reporting API key is invalid or not provided

Folders DTO:

Property	Type	Description
folders	FolderDTO[]	A list of folders

Folder DTO:

Property	Type	Description
folderId	int	The Highlight unique identifier of the folder
name	string	The name of the folder

Note: Empty folders are returned. Empty folders do not contain any watches.

Having obtained a list of folder IDs, you can limit the data returned by using the list in the API query. These are example queries, where three folders are specified with the IDs 12345,22356 and 62487:

Get Tree Data - https://reportingapi.highlighter.net/api/v2/tree/watch?folderIds=12345,22356,62487
Get Bearer Summary Data - https://reportingapi.highlighter.net/api/v2/summary/bearer?folderIds=12345,22356,62487
Get Broadband Summary Data - https://reportingapi.highlighter.net/api/v2/summary/broadband?folderIds=12345,22356,62487
Get Cellular Summary Data - https://reportingapi.highlighter.net/api/v2/summary/cellular?folderIds=12345,22356,62487
Get Device Inventory Data - https://reportingapi.highlighter.net/api/v2/tree/device?folderIds=12345,22356,62487

Bearer Summary

Get Bearer Summary Data

Obtain the summary reporting data for bearers - ADSL, SDSL and Dedicated Access watches with the given supplied filters.

HTTP Header:

x-api-key: The reporting api key (supplied by Highlight Support)

URL: https://reportingapi.highlighter.net/api/v2/summary/bearer

Http Query String Parameters

All parameters are optional and can be provided in any order.

isBusinessHours: True if looking at BusinessHours time period, False if looking at 24 Hour time period. Default: False
lastNDays: Go back N days from today. That is the start of the time window the search filters from. Default: 7 days
fromDate: Date String (DateTime.Parse) - That is the start of the time window the search filters from.
toDate: Date String (Datetime.Parse) - That is the end of the time window the search filters to. Default: Today's/current date.
dateGranularity: String (Day | Month) - Either retrieve the Day or Month data. Default: Day
folderIds: Integer - Optional list of folder or location IDs to limit the data returned and improve speed. Default: Empty (no limit, returns data from all child folders)
outputAvailability: If True, the results should include Availability related properties, under the Availability child. If false, the Availability child is omitted from the results. Default: False
outputLoad: If True, the results should include Load related properties, under the Load child. If false, the Load child is omitted from the results. Default: False
outputHealth: If True, the results should include Health related properties, under the Health child. If false, the Health child is omitted from the results. Default: False

Example:
https://reportingapi.highlighter.net/api/v2/summary/bearer?isBusinessHours=true&fromDate=2021-06-17&toDate=2021-06-18&outputAvailability=true&outputHealth=true&outputLoad=true&dateGranularity=Day

HTTP Response:

200 – OK: A successful request. A JSON array of summaries will be returned
400 – Bad Request: The reporting API key is invalid or not provided
The date filters are out of range / incorrect
The ‘dateGranularity’ value is invalid
The estimated response payload is greater than ~1gb
One or more of the folderIds are not valid (do not reside under the ReportingApi key or does not exist)

SummaryDto:

Property	Type	Description
watchId	int	The Highlight unique identifier of the watch
date	string	The date of the summary record. Formatted as yyyy-MM-dd
isBusinessHours	boolean	Does the summary relate to the business hours (true) or the whole day (false)
dateGranularity	string	“Day” \| “Month” – Is the summary related to a day’s data or a month
lastDateSummarised	string	The date when the summary record was last updated. This can be different to the ‘date’ when ‘patching’ occurs.
avail	AvailabilityDto	Availability related content. Must have outputAvailability=true for this to be populated. Nothing delivered if not defined. Avail column will be returned with null.
load	LoadDto	Load related content. Must have outputLoad=true for this to be populated. Default: Nothing delivered if not defined. Load column will be returned with null.
health	HealthDto	Health related content. Must have outputHealth=true for this to be populated. Default: Nothing delivered if not defined. Health column will be returned with null.

AvailabilityDto:

Property	Type	Description
actualPc	decimal	The actual availability reported for the watch for the period selected.
slaTargetPc	decimal	Target uptime of the watch, expressed as a percentage, configured as part of the ‘Edit Watch’ dialog.
slaBreachDur	int	The time, expressed in seconds, which the watch was unavailable in excess of the SLA target once the excluded events have been removed from the calculation.
outagesDur	int	Outage time of the watch, over the selected period (minutes). Outages during maintenance windows are excluded from the calculations.
siteActualPc	decimal	Uptime of the location which contains this site watch (%). Highlight will consider all links for this location which are identified as 'Site Links' in their configuration and only register a site outage if all links in that group are down at the same time
siteSlaBreachDur	int	The time, expressed in seconds, which the link was unavailable in excess of the SiteSLA target.
slaSiteAvailabilityTargetPc	decimal	The SLA availability target percentage for the site - as set in the location. Must have ‘Site link’ checked in the watch. Up to 3 decimal places.

HealthDto:

Property	Type	Description
availIssScore	decimal	Availability: A number from 0 to 10 which provides guidance to see how good 0 or bad 10 a link or test was in the selected time period, and to compare it with other locations.
hlthIssScore	decimal	Health: A number from 0 to 10 which provides guidance to see how good 0 or bad 10 a link or test was in the selected time period, and to compare it with other locations.
ldIssScore	decimal	Load: A number from 0 to 10 which provides guidance to see how good 0 or bad 10 a link or test was in the selected time period, and to compare it with other locations.
availExDur	int	Availability: An exception is when a watch left the green state (and changed to amber or red). It is shown in duration (seconds).
hlthExDur	int	Health: An exception is when a watch left the green state (and changed to amber or red). It is shown in duration (seconds).
ldExDur	int	Load: An exception is when a watch left the green state (and changed to amber or red). It is shown in duration (seconds).
availExCount	int	Availability: An exception is when a watch left the green state (and changed to amber or red). It is shown as a count of how many times the exception occurred.
hlthExCount	int	Health: An exception is when a watch left the green state (and changed to amber or red). It is shown as a count of how many times the exception occurred.
ldExCount	int	Load: An exception is when a watch left the green state (and changed to amber or red). It is shown as a count of how many times the exception occurred.
errorsPc	decimal	Number of packet errors counted as a percentage of packets received (%). Error calculations do not include any gathered during maintenance periods
congestionPc	decimal	Percent of packets discarded due to congestion as a percentage of packets sent, or (for WiFi) the average of the 95th percentile values for congestion for the time period. Congestion (discards) calculations do not include any gathered during maintenance periods
siteLdInPc	decimal?	Load In: Only relevant for ‘Hybrid WAN’ links, for comparison of traffic across identified routes. If the hybrid WAN box is not checked but this column is showing, then it will be null
siteLdOutPc	decimal?	Load Out: Only relevant for ‘Hybrid WAN’ links, for comparison of traffic across identified routes. If the hybrid WAN box is not checked but this column is showing, then it will be null

LoadDto:

Property	Type	Description
ldInAvgbps	long	The average load in calculated for the watch (bits/sec)
ldInAvgPc	decimal	The average load in calculated for the watch as a percentage of the line speed.
ldOutAvgbps	long	The average load out calculated for the watch (bits/sec)
ldOutAvgPc	decimal	The average load out calculated for the watch as a percentage of the line speed.
ldIn95Pbps	long	The 95th percentile load in calculated for the watch (bits/sec)
ldIn95PPc	decimal	The 95th percentile load in calculated for the watch as a percentage of the line speed.
ldOut95Pbps	long	The 95th percentile load out calculated for the watch (bits/sec)
ldOut95PPc	decimal	The 95th percentile load out calculated for the watch as a percentage of the line speed.
ldInPeakbps	long	The peak load in seen on the link (bits/sec), plus the load expressed as a percentage of the line speed.
ldInPeakPc	decimal	The peak load in expressed as a percentage of the line speed.
ldOutPeakbps	long	The peak load out seen on the link (bits/sec), plus the load expressed as a percentage of the line speed.
ldOutPeakPc	decimal	The peak load out expressed as a percentage of the line speed.
volInB	long	The volume in of traffic which passed over the link (bytes)
volOutB	long	The volume out of traffic which passed over the link (bytes)
burstInDur	int	Inbound data. Time in seconds that this watch exceeded its bandwidth.
burstOutDur	int	Outbound data. Time in seconds that this watch exceeded its bandwidth.
burstInVolB	long	Volume of inbound data over the selected period which was sent or received in excess of the watch bandwidth (bytes)
burstOutVolB	long	Volume of outbound data over the selected period which was sent or received in excess of the watch bandwidth (bytes)
ldChangePc	decimal	The change in the percent value of the 95th percentile load between the previous period and current period. Highlight will look at both In and Out change and use the larger.
volChangeB	long	The volume change between the previous period and current period. (bytes)

Example Returned JSON:

❴ "date": "2021-06-17", "watchId": 19751, "isBusinessHours": true, "dateGranularity": "Day", "lastDateSummarised": "2021-06-17", "health": ❴ "availIssScore": 5.2, "hlthIssScore": 3.1, "ldIssScore": 2.8, "availExDur": 10, "hlthExDur": 40, "ldExDur": 20, "availExCount": 1, "hlthExCount": 2, "ldExCount": 6, "errorsPc": 1.0400000, "congestionPc": 2.6000000, "siteLdInPc": null, "siteLdOutPc": null ❵ "load": ❴ "ldInAvgbps": 190000, "ldInAvgPc": 0.200000, "ldOutAvgbps": 380000, "ldOutAvgPc": 0.400000, "ldIn95Pbps": 1045000, "ldIn95PPc": 1.100000, "ldOut95Pbps": 1140000, "ldOut95PPc": 1.200000, "ldInPeakbps": 5510000, "ldInPeakPc": 5.800000, "ldOutPeakbps": 4845000, "ldOutPeakPc": 5.100000, "volInB": 1217525202, "volOutB": 1991284535, "burstInDur": 0, "burstOutDur": 0, "burstInVolB": 0, "burstOutVolB": 0, "ldChangePc": -14.500000, "volChangeB": -1900718929 ❵ "avail": ❴ "actualPc": 100.000000000000000, "slaTargetPc": 98.500, "slaBreachDur": 0, "outagesDur": 0, "siteActualPc": 100.000000000000000, "siteSlaBreachDur": null, "slaSiteAvailabilityTargetPc": 99.990, ❵ ❵

Broadband Summary

Get Broadband Summary Data

Obtain the summary reporting data for Broadband Circuits.

HTTP Header:

x-api-key: The reporting api key (supplied by Highlight Support)

URL: https://reportingapi.highlighter.net/api/v2/summary/broadband

Http Query String Parameters

All parameters are optional and can be provided in any order.

isBusinessHours: True if looking at BusinessHours time period, False if looking at 24 Hour time period. Default: False
lastNDays: Go back N days from today. That is the start of the time window the search filters from. Default: 7 days
fromDate: Date String (DateTime.Parse) - That is the start of the time window the search filters from.
toDate: Date String (Datetime.Parse) - That is the end of the time window the search filters to. Default: Today's/current date.
dateGranularity: String (Day | Month) - Either retrieve the Day or Month data. Default: Day
folderIds: Integer - Optional list of folder or location IDs to limit the data returned and improve speed. Default: Empty (no limit, returns data from all child folders)

Example:
https://reportingapi.highlighter.net/api/v2/summary/broadband?isBusinessHours=true&fromDate=2021-06-17&toDate=2021-06-18&dateGranularity=Day

HTTP Response:

200 – OK: A successful request. A JSON array of Summaries will be returned
400 – Bad Request: The reporting API key is invalid or not provided
The date filters are out of range / incorrect
The ‘dateGranularity’ value is invalid
The estimated response payload is greater than ~1gb
One or more of the folderIds are not valid (do not reside under the ReportingApi key or does not exist)

SummaryDto:

Property	Type	Description
watchId	int	The Highlight unique identifier of the watch
date	string	The date of the summary record. Formatted as yyyy-MM-dd
isBusinessHours	boolean	Does the summary relate to the business hours (true) or the whole day (false)
dateGranularity	string	“Day” \| “Month” – Is the summary related to a day’s data or a month
lastDateSummarised	string	The date when the summary record was last updated. This can be different to the ‘date’ when ‘patching’ occurs.
broadband	BroadbandDto	Broadband related content

BroadbandDto:

Property	Type	Description
lowSpeedDown	int?	Lowest recorded receive speed (in bytes) in the time period for the monitored interface. Null if NA
lowSpeedUp	int?	Lowest recorded transmit speed (in bytes) in the time period for the monitored interface. Null if NA
speedChanges	int	The number of instances of a speed change in the reporting period, either downstream or upstream

Example Returned JSON:

❴ "watchId": 50640, "date": "2022-01-15", "isBusinessHours": true, "dateGranularity": "Day", "lastDateSummarised": "2022-01-15", "broadband": ❴ "lowSpeedDown": 216000, "lowSpeedUp": 444000, "speedChanges": 1 ❵ ❵

Cellular Summary

Get Cellular Summary Data

Obtain the summary reporting data for Cellular Circuits.

HTTP Header:

x-api-key: The reporting api key (supplied by Highlight Support)

URL: https://reportingapi.highlighter.net/api/v2/summary/cellular

Http Query String Parameters

All parameters are optional and can be provided in any order.

isBusinessHours: True if looking at BusinessHours time period, False if looking at 24 Hour time period. Default: False
lastNDays: Go back N days from today. That is the start of the time window the search filters from. Default: 7 days
fromDate: Date String (DateTime.Parse) - That is the start of the time window the search filters from.
toDate: Date String (Datetime.Parse) - That is the end of the time window the search filters to. Default: Today's/current date.
dateGranularity: String (Day | Month) - Either retrieve the Day or Month data. Default: Day
folderIds: Integer - Optional list of folder or location IDs to limit the data returned and improve speed. Default: Empty (no limit, returns data from all child folders)

Example:
https://reportingapi.highlighter.net/api/v2/summary/cellular?isBusinessHours=true&fromDate=2021-06-17&toDate=2021-06-18&dateGranularity=Day

HTTP Response:

200 – OK: A successful request. A JSON array of Summaries will be returned
400 – Bad Request: The reporting API key is invalid or not provided
The date filters are out of range / incorrect
The ‘dateGranularity’ value is invalid
The estimated response payload is greater than ~1gb
One or more of the folderIds are not valid (do not reside under the ReportingApi key or does not exist)

SummaryDto:

Property	Type	Description
watchId	int	The Highlight unique identifier of the watch
date	string	The date of the summary record. Formatted as yyyy-MM-dd
isBusinessHours	boolean	Does the summary relate to the business hours (true) or the whole day (false)
dateGranularity	string	“Day” \| “Month” – Is the summary related to a day’s data or a month
lastDateSummarised	string	The date when the summary record was last updated. This can be different to the ‘date’ when ‘patching’ occurs.
cellular	CellularDto	Cellular related content

CellularDto:

Property	Type	Description
signalScoreAvg	decimal?	The average signal strength score for the selected period
signalScoreMin	decimal?	The minimum/worst signal strength score for the selected period
signalScoreMax	decimal?	The maximum/best signal strength score for the selected period
signalScoreWithinThresholdPc	decimal?	The percent of time signal strength score was within the threshold for the selected period
towerChangeCount	int?	Number of times the tower changed for the selected period. Can be a null value.
networkChangeCount	int?	Number of times the network changed for the selected period. Can be a null value.
radioChangeCount	int?	Number of times the radio changed for the selected period. Can be a null value.
towerList	string	A pipe separated list of tower ids used for the selected period
networkList	string	A pipe separated list of networks used for the selected period
radioList	string	A pipe separated list of radios used for the selected period

Example Returned JSON:

❴ "watchId": 19751, "date": "2021-12-07", "isBusinessHours": true, "dateGranularity": "Day", "lastDateSummarised": "2021-12-07", "cellular": ❴ "signalScoreAvg": 3.9, "signalScoreMin": 0, "signalScoreMax": 5 "signalScoreWithinThresholdPc": 98.64, "towerChangeCount": 4, "networkChangeCount": 6, "radioChangeCount": 14, "towerList": "102123735|102123736|102123732", "networkList": "EE|Unknown|3 UK", "radioList": "Wcdma|Lte|unknown" ❵ ❵

Tunnel Summary

Get Tunnel Summary Data

Obtain the summary reporting data for SD-WAN VPN Tunnels.

HTTP Header:

x-api-key: The reporting api key (supplied by Highlight Support)

URL: https://reportingapi.highlighter.net/api/v2/summary/tunnel

Http Query String Parameters

All parameters are optional and can be provided in any order.

isBusinessHours: True if looking at BusinessHours time period, False if looking at 24 Hour time period. Default: False
lastNDays: Go back N days from today. That is the start of the time window the search filters from. Default: 7 days
fromDate: Date String (DateTime.Parse) - That is the start of the time window the search filters from.
toDate: Date String (Datetime.Parse) - That is the end of the time window the search filters to. Default: Today's/current date.
dateGranularity: String (Day | Month) - Either retrieve the Day or Month data. Default: Day
folderIds: Integer - Optional list of folder or location IDs to limit the data returned and improve speed. Default: Empty (no limit, returns data from all child folders)
outputAvailability: If True, the results should include Availability related properties, under the Availability child. If false, the Availability child is omitted from the results. Default: False
outputLoad: If True, the results should include Load related properties, under the Load child. If false, the Load child is omitted from the results. Default: False
outputHealth: If True, the results should include Health related properties, under the Health child. If false, the Health child is omitted from the results. Default: False

Example:
https://reportingapi.highlighter.net/api/v2/summary/tunnel?isBusinessHours=true&fromDate=2021-06-17&toDate=2021-06-18&dateGranularity=Day&outputLoad=true&folderIds=46,75

HTTP Response:

200 – OK: A successful request. A JSON array of Summaries will be returned
400 – Bad Request: The reporting API key is invalid or not provided
The date filters are out of range / incorrect
The ‘dateGranularity’ value is invalid
The estimated response payload is greater than ~1gb
One or more of the folderIds are not valid (do not reside under the ReportingApi key or does not exist)

SummaryDto:

Property	Type	Description
watchId	int	The Highlight unique identifier of the watch
date	string	The date of the summary record. Formatted as yyyy-MM-dd
isBusinessHours	boolean	Does the summary relate to the business hours (true) or the whole day (false)
dateGranularity	string	“Day” \| “Month” – Is the summary related to a day’s data or a month
lastDateSummarised	string	The date when the summary record was last updated. This can be different to the ‘date’ when ‘patching’ occurs.
		See Bearer Summary section above for details on AvailabilityDto, LoadDto and HealthDto
avail	AvailabilityDto	Availability related content. Must have outputAvailability=true for this to be populated. Nothing delivered if not defined. Avail column will be returned with null.
load	LoadDto	Load related content. Must have outputLoad=true for this to be populated. Nothing delivered if not defined. Load column will be returned with null.
health	HealthDto	Health related content. Must have outputHealth=true for this to be populated. Nothing delivered if not defined. Health column will be returned with null.

GetTunnels JSON output:

❴ "watchId": 524927, "date": "2022-08-01", "isBusinessHours": false, "dateGranularity": "Month", "lastDateSummarised": "2022-08-19", "health": ❴ "availIssScore": 0, "hlthIssScore": 0, "ldIssScore": 0, "availExDur": 0, "hlthExDur": 0, "ldExDur": 0, "availExCount": 0, "hlthExCount": 0, "ldExCount": 0, "errorsPc": null, "congestionPc": null, "siteLdInPc": null, "siteLdOutPc": null ❵, "load": ❴ "ldInAvgbps": null, "ldInAvgPc": null, "ldOutAvgbps": null, "ldOutAvgPc": null, "ldIn95Pbps": null, "ldIn95PPc": null, "ldOut95Pbps": null, "ldOut95PPc": null, "ldInPeakbps": null, "ldInPeakPc": null, "ldOutPeakbps": null, "ldOutPeakPc": null, "volInB": 0, "volOutB": 63486000, "burstInDur": null, "burstOutDur": null, "burstInVolB": null, "burstOutVolB": null, "ldChangePc": null, "volChangeB": -7100 ❵, "avail": ❴ "actualPc": 100.000000000000000, "slaTargetPc": null, "slaBreachDur": null, "outagesDur": 0, "siteActualPc": null, "siteSlaBreachDur": null, "slaSiteAvailabilityTargetPc": null ❵, ❵

Performance Test Summaries

There are three separate performance test summaries:

ICMP/TCP/UDP: This will return data on these three test types
Precision: This will return data for precision delay tests only
MOS: This will return data for MOS tests only
HTTP Server: This will return data forHTTP Server tests only

Find out more about different performance test types.

Get Performance Test Summary Data

Obtain the summary reporting data for Performance Tests.

HTTP Header:

x-api-key: The reporting api key (supplied by Highlight Support)

URL

ICMP/TCP/UDP: https://reportingapi.highlighter.net/api/v2/summary/icmptcpudp
Precision: https://reportingapi.highlighter.net/api/v2/summary/precision
MOS: https://reportingapi.highlighter.net/api/v2/summary/mos
HTTP Server: https://reportingapi.highlighter.net/api/v2/summary/httpserver

Http Query String Parameters

All parameters are optional and can be provided in any order.

isBusinessHours: True if looking at BusinessHours time period, False if looking at 24 Hour time period. Default: False
lastNDays: Go back N days from today. That is the start of the time window the search filters from. Default: 7 days
fromDate: Date String (DateTime.Parse) - That is the start of the time window the search filters from.
toDate: Date String (Datetime.Parse) - That is the end of the time window the search filters to. Default: Today's/current date
dateGranularity: String (Day | Month) - Either retrieve the Day or Month data. Default: Day
folderIds: Integer - Optional list of folder or location IDs to limit the data returned and improve speed. Default: Empty (no limit, returns data from all child folders)

Examples:

ICMP/TCP/UDP: https://reportingapi.highlighter.net/api/v2/summary/icmptcpudp?isBusinessHours=true&fromDate=2021-06-17&toDate=2021-06-18&dateGranularity=Day&folderIds=46,75
Precision: https://reportingapi.highlighter.net/api/v2/summary/precision?isBusinessHours=true&fromDate=2021-06-17&toDate=2021-06-18&dateGranularity=Day&folderIds=46,75
MOS: https://reportingapi.highlighter.net/api/v2/summary/mos?isBusinessHours=true&fromDate=2021-06-17&toDate=2021-06-18&dateGranularity=Day&folderIds=46,75
HTTP Server: https://reportingapi.highlighter.net/api/v2/summary/httpserver?isBusinessHours=true&fromDate=2021-06-17&toDate=2021-06-18&dateGranularity=Day&folderIds=46,75

HTTP Response:

200 – OK: A successful request. A JSON array of Summaries will be returned
400 – Bad Request: The reporting API key is invalid or not provided
The date filters are out of range / incorrect
The ‘dateGranularity’ value is invalid
The estimated response payload is greater than ~1gb
One or more of the folderIds are not valid (do not reside under the ReportingApi key or does not exist)

SummaryDto:

Property	Type	Description
watchId	int	The Highlight unique identifier of the watch
date	string	The date of the summary record. Formatted as yyyy-MM-dd
isBusinessHours	boolean	Does the summary relate to the business hours (true) or the whole day (false)
dateGranularity	string	“Day” \| “Month” – Is the summary related to a day’s data or a month
lastDateSummarised	string	The date when the summary record was last updated. This can be different to the ‘date’ when ‘patching’ occurs.
		See Bearer Summary section above for details on HealthDto
health	HealthDto	Health related content. Must have outputHealth=true for this to be populated. errorsPc, congestionPc, siteLdInPc, siteLdOutPc will be zero or null value as they do not apply. Nothing delivered if not defined. Health column will be returned with null.
performanceSummary	PerformanceSummaryDto	See PerformanceSummaryDto
mosScoreAvg	decimal	For MOS summary only: The average MOS score for the period. Obtained from the summary tables.
mosScore95Pc	decimal	For MOS summary only: The 95th percentile MOS score for the period. Obtained from the summary tables.

PerformanceSummaryDto:

All values are obtained from the summary tables.

Property	Type	Description
withinTargetPc	decimal	Of the total tests in the time period, what percent were within all configured target/threshold parameters (%). For HTTP Server tests only: Of the tests that had no error, take the percentage of tests with ‘Total Time’ (delayAvg) less than or equal to the threshold.
delayJitter	decimal?	Application response jitter as reported by the router (milliseconds).
delayAvg	decimal	Round-trip average application response (milliseconds).
delay95Pc	decimal	Round-trip 95th percentile application response (milliseconds).
changeInDelay	decimal	The change in value of the average application response between the previous period and current period.
packetLossPc	decimal?	Test packets lost (%).
successPc	decimal?	For HTTP Server tests only: Of the total tests in the time period, what percent had no error AND were less than or equal to the threshold.
failurePc	decimal?	For HTTP Server tests only: Of the total tests in the time period, what percent had an error.

Note: Source Country is not included

Performance Test Summaries - Examples

Example GetICMPTCPUDPSummaries JSON output:

❴ "watchId": 49234, "date": "2022-09-29", "isBusinessHours": false, "dateGranularity": "Day", "lastDateSummarised": "2022-09-29", "health": ❴ "availIssScore": 1.5, "hlthIssScore": 2.2, "ldIssScore": 0, "availExDur": 0, "hlthExDur": 900, "ldExDur": 0, "availExCount": 0, "hlthExCount": 1, "ldExCount": 0, "errorsPc": null, "congestionPc": null, "siteLdInPc": null, "siteLdOutPc": null ❵, "performanceSummary": ❴ "withinTargetPc": 98.229166666666, "delayJitter": 0, "delayAvg": 2, "delay95Pc": 1, "changeInDelay": 0, "packetLossPc": 1.076388888888, "successPc": null, "failurePc": null ❵, ❵

Example GetPrecisionSummaries JSON output:

❴ "watchId": 5511194, "date": "2022-09-26", "isBusinessHours": false, "dateGranularity": "Day", "lastDateSummarised": "2022-09-26", "health": ❴ "availIssScore": 4.3, "hlthIssScore": 8.3, "ldIssScore": 0, "availExDur": 0, "hlthExDur": 32940, "ldExDur": 0, "availExCount": 0, "hlthExCount": 1, "ldExCount": 0, "errorsPc": null, "congestionPc": null, "siteLdInPc": null, "siteLdOutPc": null ❵, "performanceSummary": ❴ "withinTargetPc": 54.444444444444, "delayJitter": 74.396000, "delayAvg": 230.741000, "delay95Pc": 435.183000, "changeInDelay": 0.000000, "packetLossPc": 6.533333333333333, "successPc": null, "failurePc": null ❵, ❵

Example GetMosSummaries JSON output:

❴ "watchId": 49377, "date": "2022-08-01", "isBusinessHours": false, "dateGranularity": "Month", "lastDateSummarised": "2022-08-01", "health": ❴ "availIssScore": 0.6, "hlthIssScore": 1.7, "ldIssScore": 0, "availExDur": 180, "hlthExDur": 540, "ldExDur": 0, "availExCount": 1, "hlthExCount": 1, "ldExCount": 0, "errorsPc": null, "congestionPc": null, "siteLdInPc": null, "siteLdOutPc": null ❵, "performanceSummary": ❴ "withinTargetPc": 98.708375378405, "delayJitter": 4, "delayAvg": 85, "delay95Pc": 87, "changeInDelay": 0, "packetLossPc": 0.358875269344148, "successPc": null, "failurePc": null ❵, "mosScoreAvg": 4.298065, "mosScore95Pc": 4.34 ❵

Example GetHttpServerSummaries JSON output:

❴ "watchId": 49377, "date": "2024-04-01", "isBusinessHours": false, "dateGranularity": "Month", "lastDateSummarised": "2024-04-01", "health": ❴ "availIssScore": 0.6, "hlthIssScore": 1.7, "ldIssScore": 0, "availExDur": 180, "hlthExDur": 540, "ldExDur": 0, "availExCount": 1, "hlthExCount": 1, "ldExCount": 0, "errorsPc": null, "congestionPc": null, "siteLdInPc": null, "siteLdOutPc": null ❵, "performanceSummary": ❴ "withinTargetPc": 98.708375378405, "delayJitter": null, "delayAvg": 85, "delay95Pc": 87, "changeInDelay": 0, "packetLossPc": null, "successPc": 23.52, "failurePc": 35.23 ❵, ❵

Wireless Access Point Summary

Get Wireless Access Point Summary Data

Obtain the summary reporting data for Wireless Access Points.

HTTP Header:

x-api-key: The reporting api key (supplied by Highlight Support)

URL: https://reportingapi.highlighter.net/api/v2/summary/wirelessAccessPoint?

Http Query String Parameters

All parameters are optional and can be provided in any order.

isBusinessHours: True if looking at BusinessHours time period, False if looking at 24 Hour time period. Default: False
lastNDays: Go back N days from today. That is the start of the time window the search filters from. Default: 7 days
fromDate: Date String (DateTime.Parse) - That is the start of the time window the search filters from.
toDate: Date String (Datetime.Parse) - That is the end of the time window the search filters to. Default: Today's/current date.
dateGranularity: String (Day | Month) - Either retrieve the Day or Month data. Default: Day
folderIds: Integer - Optional list of folder or location IDs to limit the data returned and improve speed. Default: Empty (no limit, returns data from all child folders)

Example:
https://reportingapi.highlighter.net/api/v2/summary/wirelessAccessPoint?isBusinessHours=true&fromDate=2021-06-17&toDate=2021-06-18&dateGranularity=Day

HTTP Response:

200 – OK: A successful request. A JSON array of Summaries will be returned
400 – Bad Request: The reporting API key is invalid or not provided
The date filters are out of range / incorrect
The ‘dateGranularity’ value is invalid
The estimated response payload is greater than ~1gb
One or more of the folderIds are not valid (do not reside under the ReportingApi key or does not exist)

SummaryDto:

Property	Type	Description
watchId	int	The Highlight unique identifier of the watch
date	string	The date of the summary record. Formatted as yyyy-MM-dd
isBusinessHours	boolean	Does the summary relate to the business hours (true) or the whole day (false)
dateGranularity	string	“Day” \| “Month” – Is the summary related to a day’s data or a month
lastDateSummarised	string	The date when the summary record was last updated. This can be different to the ‘date’ when ‘patching’ occurs.
		See Bearer Summary section above for details on AvailabilityDto and HealthDto
avail	AvailabilityDto	Availability related content. Must have outputAvailability=true for this to be populated. Nothing delivered if not defined. Avail column will be returned with null. siteActualPc, siteSlaBreachDur and slaSiteAvailabilityTargetPc will be zero or null value.
health	HealthDto	Health related content. Must have outputHealth=true for this to be populated. Nothing delivered if not defined. Health column will be returned with null. errorsPc, siteLdInPc, siteLdOutPc, will be zero or null value as they do not apply.

WapDto:

Property	Type	Description
ld5Avg	decimal?	The average utilisation (%) seen on the wireless networks on this WAP taken over the selected time period. 5 GHz
ld24Avg	decimal?	The average utilisation (%) seen on the wireless networks on this WAP taken over the selected time period. 2.4 GHz
ld595Pc	decimal?	The 95th percentile utilisation value (%) seen on the wireless networks on this WAP taken over the selected time period. 5 GHz
ld2495Pc	decimal?	The 95th percentile utilisation value (%) seen on the wireless networks on this WAP taken over the selected time period. 2.4 GHz
ld5PeakPc	decimal?	The peak utilisation value (%) seen on the wireless networks on this WAP taken over the selected time period. 5 GHz
ld24PeakPc	decimal?	The peak utilisation value (%) seen on the wireless networks on this WAP taken over the selected time period. 2.4 GHz
volIn	long	The volume in bytes of received wireless traffic from the WAP over the selected time period.
volOut	long	The volume in bytes of sent wireless traffic from the WAP over the selected time period.
clientCountAvg	int	The average number of devices connected to the WAP during the selected time period.
clientCountPeak	int	The highest number of devices connected to the WAP during the selected time period.
signalQualityPoorPcOfClientsAvg	decimal	An indication of how many clients attached to the WAP had signal quality problems (1 or 2 bars, less than 20dB) in the selected time period, ignoring those passing trivial amounts of traffic. Shown as a percentage. Signal problems calculations exclude maintenance periods.

Example Returned JSON:

❴ "watchId": 9523094, "date": "2023-12-01", "isBusinessHours": false, "dateGranularity": "Month", "lastDateSummarised": "2023-12-31", "health": ❴ "availIssScore": 0.9, "hlthIssScore": 0, "ldIssScore": 8.4, "availExDur": 5700, "hlthExDur": 0, "ldExDur": 306300, "availExCount": 1, "hlthExCount": 0, "ldExCount": 2, "errorsPc": null, "congestionPc": 0.0000000, "siteLdInPc": null, "siteLdOutPc": null ❵ "avail": ❴ "actualPc": 98.501872659176029, "slaTargetPc": null, "slaBreachDur": null, "outagesDur": 3600, "siteActualPc": null, "siteSlaBreachDur": null, "slaSiteAvailabilityTargetPc": null ❵ "clientCountPeak": 3, "clientCountAvg": 0, "signalQualityPoorPcOfClientsAvg": 0, "ld24Avg": 68.700000, "ld5Avg": 51.000000, "ld2495Pc": 74.600000, "ld595Pc": 54.800000, "ld24PeakPc": 78.000000, "ld5PeakPc": 61.000000, "volIn": 2150400, "volOut": 2457600 ❵

Inventory Data

Get Device Inventory Data

Obtain the SNMP device details gathered by Highlight under the given ReportingApi key.

HTTP Header:

x-api-key: The reporting api key (supplied by Highlight Support)

URL: https://reportingapi.highlighter.net/api/v2/tree/device

Http Query String Optional Parameter

folderIds: Integer - Optional list of folder or location IDs to limit the data returned and improve speed. Default: Empty (no limit, returns data from all child folders)

HTTP Response:

200 – OK: A successful request. A JSON array of Summaries will be returned
400 – Bad Request: The reporting API key is invalid or not provided

DeviceDto:

Property	Type	Description
nodeId	int	The Highlight unique identifier of the device. (DeviceNode or EndpointNode)
name	string	Name of device (as reported by the device)
ipAddress	string	IP address or DNS address of the device. Empty if from an SDWan device
vendor	string	Name of the device manufacturer. E.g. Cisco, HP, Juniper (as reported by the device)
type	string	Type of the device (as reported by the device)
sysLocation	string	The system location configured on the device
locationId	int	The Highlight identifier of the location of the device
location	string	The name of the Highlight location the device resides
name	string	Name of device (as reported by the device)
path	string	The folder path of the device. Starting from the child of the reporting API key folder.
systemDescription	string	Additional information about the device such as the full or partial OS description of the device detailing the current firmware or software version. Hover over the text to see the full information. (as reported by the device)
supportsApp	boolean	True if the device supports App reporting (NBar)
supportsPerf	boolean	True if the device supports Performance testing
supportsHost	boolean	False - this will always return false as it has been deprecated
supportsSwitch	boolean	True if the device supports Switch reporting
supportsWifi	boolean	True if the device supports WiFi
lastCheckedUtc	string	The time when Highlight last received an update of the device details in UTC. Formatted as yyyy-MM-dd HH:mm:ss
lastRestartedUtc	string	The time when the device was last restarted in UTC. Formatted as yyyy-MM-dd HH:mm:ss
serialNumber	string	The serial number as reported by the device. <Empty> if unknown
versions	string	Version of the hardware/software on the device
sysContact	string	The contact information configured on the device
simIccids	DeviceIccidDto[ ]	A list of SIM cards
licenses	DeviceLicenseDto[ ]	A list of licenses associated with the device

DeviceLicenseDto:

Property	Type	Description
name	string	The feature name of the license
type	string	The type of license. Can be one of the following values: demo, extension, gracePeriod, permanent, paidSubscription, evaluationSubscription, extensionSubscription, evalRightToUse, rightToUse, permanentRightToUse, CotermSubscription
status	string	The status of the license. Can be one of the following values: inactive, notInUse, inUse, expiredInUse, expiredNotInUse, usageCountConsumed

DeviceIccidDto:

Property	Type	Description
iccidCode	string	The ICCID code of the SIM card
imeiNumber	string	The IMEI number of the SIM card

Example Returned JSON:

❴ "nodeId": 55364, "name": 2960x-Highlight-Core, "ipAddress": 192.168.100.4, "vendor": Cisco, "type": cat29xxStack, "sysLocation": Marlow SL71AB Ground Floor "locationId": 55362, "location": Marlow, "path": NetFlow, "systemDescription": Cisco IOS Software, C2960X Software (C2960X-UNIVERSALK9-M), Version 15.2(2)E5, RELEASE SOFTWARE (fc2) Technical Support: http://www.cisco.com/techsupport Copyright (c) 1986-2016 by Cisco Systems, Inc. Compiled Thu 02-Jun-16 01:31 by prod_rel_team, "supportsApp": false, "supportsPerf": false, "supportsHost": false, "supportsSwitch": true, "supportsWifi": false, "lastCheckedUtc": 2022-05-18T05:35:26, "lastRestartedUtc": 2022-02-23T15:06:10, "serialNumber": FCW2046A3YP, "sysContact": support@kfv-services.com "versions": H/W: V05, F/W: 15.2(2)E5, S/W: 15.2(2)E5, "licenses": [ ❴ "name": lanbase, "type": cat29xxStack, "status": Unknown ❵ "simIccid": [ ❴ "code": 8944391000002667036, "imei": 356129070892028 ❵ ❴ "code": 3744391000002667082, "imei": 116129070892011 ❵ ❵ ❵

Notes

"int" vs "int?"
In the tables on this page, if the type ends in ? this means the value can also be Null