API

Last updated 22 hours ago

Was this helpful?

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 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. 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
- SLA Compliance 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:

Http Query String Optional Parameter

folderIds: Integer List - Optional comma separated 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:

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:

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:

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:

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.

adjustedPc

decimal

The availability reported for the watch for the period selected after taking into account the exclusions

exclusions

int

The number of exclusions (available on some watches only)

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

siteAdjustedPc

decimal

After taking exclusions into account - the 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

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": 98.000000000000000,
     "adjustedPc": 99.000000000000000,
     "exclusions": 5,
     "slaTargetPc": 98.500,
     "slaBreachDur": 0,
     "outagesDur": 0,
     "siteActualPc": 100.000000000000000,
     "siteAdjustedPc": 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:

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

HTTP Response:

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:

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

HTTP Response:

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" ❵ ❵

SLA Compliance Summary

Obtain the summary reporting data for 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/slacompliance

Http Query String Parameters

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

Example:

https://reportingapi.highlighter.net/api/v2/summary/slacompliance?isBusinessHours=true&fromDate=2021-06-17&toDate=2025-05-12&dateGranularity=Day

ComplianceSLADto:

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. Additional availability fields for this summary are:

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. errorsPc, congestionPc will have null values for this summary

GetSLACompliance JSON output:

[
    {
        "watchId": 19751,
        "date": "2025-04-01",
        "isBusinessHours": false,
        "dateGranularity": "Month",
        "lastDateSummarised": "2025-04-30",
        "health": {
            "availIssScore": 3.8,
            "hlthIssScore": 0,
            "ldIssScore": 0,
            "availExDur": 129780,
            "hlthExDur": 0,
            "ldExDur": 0,
            "availExCount": 3,
            "hlthExCount": 0,
            "ldExCount": 0,
            "errorsPc": null,
            "congestionPc": null,
            "siteLdInPc": 55.3800,
            "siteLdOutPc": 58.4800
        },
        "load": {
            "ldInAvgbps": 0,
            "ldInAvgPc": 0.000000,
            "ldOutAvgbps": 0,
            "ldOutAvgPc": 0.000000,
            "ldIn95Pbps": 20000,
            "ldIn95PPc": 0.100000,
            "ldOut95Pbps": 20000,
            "ldOut95PPc": 0.100000,
            "ldInPeakbps": 20000,
            "ldInPeakPc": 0.100000,
            "ldOutPeakbps": 20000,
            "ldOutPeakPc": 0.100000,
            "volInB": 3225098626,
            "volOutB": 3738658266,
            "burstInDur": 0,
            "burstOutDur": 0,
            "burstInVolB": 0,
            "burstOutVolB": 0,
            "ldChangePc": 0.100000,
            "volChangeB": 54805622
        },
        "avail": {
            "actualPc": 95.137538205056960,
            "slaTargetPc": 98.500,
            "slaBreachDur": 65531,
            "adjustedPc": 95.971103084190052,
            "exclusions": 3,
            "outagesDur": 126000,
            "siteActualPc": 95.144484579049736,
            "siteAdjustedPc": 95.97804945818,
            "siteSlaBreachDur": null,
            "slaSiteAvailabilityTargetPc": 98.123
        }
    }
]

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:

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:

ComplianceSLADto:

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

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": 98.000000000000000,
     "adjustedPc": 99.000000000000000,
    "exclusions": 5,
    "slaTargetPc": null,
    "slaBreachDur": null,
    "outagesDur": 0,
    "siteActualPc": null,
    "siteAdjustedPc": null,
    "siteSlaBreachDur": null,
    "slaSiteAvailabilityTargetPc": null
  ❵,
❵

Performance Test Summaries

There are four separate performance test summaries. Each returns data for the specified test type only.

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)

Test types

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.

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:

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.

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 below

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:

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

HTTP Response:

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. 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:

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

PreviousThe Reporting API NextAudit Log

Last updated 22 hours ago

Was this helpful?