Insight Open APIs

Introduction

You can install open APIs on your analyzer instance allowing the extraction of real-time measurements and key performance indicators (KPIs) related to Latency, Throughput and Reliability.

The APIs can extract selected data available in the existing visual dashboards such as latency measurement per protocol, aggregated KPIs for network and application latency levels and new network quality qualifiers such as volatility and stability.

The API output data is presented in JSON format for a given pair or QoSAgent-Reflector. The result can then be easily integrated into other external systems.

The A) Connectivity Insight API allows users to ask the analyzer instance for connectivity performance data about a specific QoSAgent using its AgentID.

The B) Throughput Insight API allows users to ask the analyzer instance for real time throughput measurements using the Lifbe protocol (when configured and activated). Download and Upload results in Mbps and associated Jitter results are retrieved using this API.

The C) Latency Insight API can be used to retrieve the latency measurements for a specific protocol and for a specific agent in a user determined time range set in seconds.

The D) Geoloc Insight API is used to query the latest average latency measured and its geographic coordinates in GPS format (when available and configured). Adding the optional time_range query parameter to the /api/v1/geoloc endpoint, allows users to specify the time period in seconds for which they want to retrieve historical geolocation data.

The E) Twamp Insight API can be used to query latest and detailed latency levels measured using the TWAMP Protocol (RFC 5357) for a given QoSAgent. The latency results are split between forward latency in ms, return latency in ms and processing latency in ms (i.e. time spent within the Reflector).

The F) Forecast Insight API provides the latest forecasted measures using statistical based mean and projection.

The G) Radio Insight API provides the latest radio/cellular measures.

The H) Networks API provides all the customer_id / networks on the analyzer.

The I) Agents API provides all the QoS-Agents attached to a customer_id, can include either, only the ID or, also including the metadata.

The J) Anomalies Insight API detects and reports network anomalies across protocols with detailed anomaly metrics and pattern analysis.

The K) Performance Trends API analyzes agent performance trends over time, comparing current performance against historical baselines to identify degradation patterns.

The L) Health Report API generates comprehensive network health reports with agent rankings, performance distribution, and actionable recommendations.

The M) Agent Rankings API ranks all agents by performance metrics and trends, identifying top and bottom performers across your network.

The N) Correlation Analysis API detects correlation patterns between agents to identify network-wide issues affecting multiple locations simultaneously.

The O) Degradation Alerts API proactively identifies agents showing performance degradation above configurable thresholds over specified time periods.

The P) iPerf Throughput Insight API returns TCP and UDP throughput from iPerf measurements for a given QoSAgent.

The API requires that you open and secure the port 12099 on your analyzer instance.

Usage

Authentication

The API uses API key authentication. Include your API key in the x-api-key header with every request:

x-api-key: your_api_key_here

You can retrieve the API key by examining container logs:

docker logs <api_container_ID>| grep "API Key:"

A) Connectivity Insight API

Results use mixed windows: last 10 seconds for per-protocol latency, 5 minutes for jitter/volatility/stability, 30 seconds for QoE, 12 hours for throughput, and 1 week for metadata and expected values.

Used with the /api/v1/ci endpoint. You can see the measurements for the agents using the agent_id and customer_id parameters:

curl -H "x-api-key: your_api_key_here" -s -k https://<analyzer_IP>:12099/api/v1/ci?agent_id=<agentID>&customer_id=<customerID>

sample output:

{
    "CustomerID": "0",
    "agentID": "0",
    "KPIs": {
        "tcpMs": 8.94,
        "udpMs": 9.53,
        "httpMs": 9.09,
        "httpsMs": 18,
        "icmpMs": 9.2,
        "twampMs": 9.45,
        "downloadThroughputMbps": 1383.58,
        "uploadThroughputMbps": 950.06,
        "networkLatencyMs": 9.32,
        "applicationLatencyMs": 11.39,
        "packetLossRatePercent": 0,
        "jitterMs": 6.1,
        "volatilityPercent": 46.2,
        "networkStabilityPercent": 65.5,
        "connectivityHealth": "Warning",
        "qualityOfExperience": 4.921,
        "expectedLatencyMS": 40,
        "expectedStabilityPercent": 98,
        "expectedPacketLossPercent": 0.1
    },
    "Attributes": {
        "time": "2025-03-26T14:01:23.305Z",
        "agentName": "GenericQoSAgent",
        "hardware": "Not-Applicable",
        "networkName": "OutScale-Network",
        "networkType": "Outscale",
        "gpsPos": "48.864716,2.349014",
        "details": "Generic QoSAgent preinstalled with OMI",
    },
    "APInotes": {
        "comment": "Results from LatenceTech ConnectivityInsight API version 2.1",
        "documentation": "Refer to docs.latence.ca for API details and data structure"
    }
}

New connectivity insights v2

GET /v2/ci?customer_id={customer_id}&agent_id={agent_id}

The v2 endpoint doesn't provide the expected values, the volatilityPercent, networkStabilityPercent, connectivityHealth, as well as the metadata.

This was made to be a lightweight version of the /v1/ci.

Results use the last 10 seconds for per-protocol latency, 5 minutes for jitter and packet loss, 12 hours for throughput, and 30 seconds for QoE.

B) Throughput Insight API

Returns the latest LIFBE values from the last 2 hours for throughput and jitter, and from the last 12 hours for packet loss.

Used with the /api/v1/lifbe endpoint. You can display the real time data of throughput measurements using the Lifbe protocol using the agent_id and customer_id parameters:

curl -H "x-api-key: your_api_key_here" -s -k https://<analyzer_IP>:12099/api/v1/lifbe?agent_id=<agentID>&customer_id=<customerID>

sample output:

{
    "agentID": "1",
    "time": "2024-05-17T15:00:04.735Z",
    "lifbeDownload": 542.48,
    "lifbeUpload": 49.89,
    "jitterDownload": 1.23,
    "jitterUpload": 3.13,
    "networkInterface": "MOBILE",
    "networkType": "MOBILE_5G"
}

C) Latency Insight API

Requires time_range (seconds) or chosen_time; there is no default window.

Used with the /api/v1/latency endpoint. You can see the measurements for a specific protocol for a specific agent in a user determined time range by adding 3 optional arguments to the query in addition to agent_id and customer_id parameters:

1) protocol (tcp, udp ,http, https, icmp, twamp)
2) time_range (in seconds)
3) chosen_time

curl -H "x-api-key: your_api_key_here" -s -k https://<analyzer_IP>:12099/api/v1/latency?agent_id=<agentID>&customer_id=<customerID>&protocol=tcp&time_range=400

sample output:

[   
    {
        "agentID": "1",
        "time": "2024-05-17T15:01:26.183Z",
        "measurement": "tcp_result",
        "value": 15.61
    },
    {
        "agentID": "1",
        "time": "2024-05-17T15:01:28.215Z",
        "measurement": "tcp_result",
        "value": 15.233
    }
]

Optional: the protocol parameter is optional, if not set, all protocols will be shown.

Optional: using the chosen_time parameter allows you to query data for a given time period, format start_time,end_time (ex: 2025-05-30T10:00:00Z,2025-06-15T17:00:00Z).
To not use with time_range.

The time specified has to be UTC, or the time zone configured for the analyzer (UTC by default)

curl -H "x-api-key: your_api_key_here" -s -k https://<analyzer_IP>:12099/api/v1/latency?customer_id=<customerID>&agent_id=<agentID&chosen_time=2025-07-07T16:12:26Z
2025-07-07T16:12:34Z

sample output:

[
  {
    "CustomerID": "0",
    "agentID": "9",
    "time": "2025-07-07T16:12:25.000Z",
    "tcp": 46.364,
    "udp": 48.355,
    "http": 49.572,
    "https": 96.752,
    "twamp": 47.791,
    "icmp": 48.5
  },
  {
    "CustomerID": "0",
    "agentID": "9",
    "time": "2025-07-07T16:12:30.000Z",
    "tcp": 48.233,
    "udp": 48.005,
    "http": 47.985,
    "https": 96.531,
    "twamp": 47.812,
    "icmp": 48.5
  }
]

D) Geoloc Insight API

Uses the last 1 minute by default, or the period set by time_range (seconds).

You can use the mobile application (or a modem/CPE with geolocation retrieval enabled) and send GPS data to the analyzer, you will be able to check the current state of the latency as well as historical data with previous location.

Used with the /api/v1/geoloc endpoint. You can add the agent_id and customer_id parameters and an optional time_range (in seconds) to get historical data:

curl -H "x-api-key: your_api_key_here" -s -k https://<analyzer_IP>:12099/api/v1/geoloc?agent_id=<agentID>&customer_id=<customerID>

For historical data:

curl -H "x-api-key: your_api_key_here" -s -k https://<analyzer_IP>:12099/api/v1/geoloc?agent_id=<agentID>&customer_id=<customerID>&time_range=400

sample output:

{
    "agentID": "50",
    "time": "2024-05-17T15:01:20Z",
    "altitude": "39.1",
    "latitude": "45.4961001",
    "longitude": "-73.5619866",
    "applicationLatency": 10.213
}

E) Twamp Insight API

Returns the latest TWAMP deltas from the last 5 minutes.

This API can be used to query latest and detailed latency levels measured using the TWAMP Protocol (RFC 5357) for a given QoSAgent. The latency results are as follow:
- TwampFwdDeltaMs = TWAMP Forward Delta (i.e. latency between QoSAgent -> Reflector) in milliseconds
- TwampRevDeltaMs = TWAMP Reverse Delta (i.e. latency between Reflector -> QoSAgent) in milliseconds
- TwampProcDeltaMs = TWAMP processing Delta (i.e. latency occurring within Reflector) in milliseconds

Used with the /api/v1/twamp endpoint. You can add the agent_id and customer_id parameters:

curl -H "x-api-key: your_api_key_here" -s -k https://<analyzer_IP>:12099/api/v1/twamp?agent_id=<agentID>&customer_id=<customerID>

sample output:

{
    "agentID": "12",
    "time": "2024-06-21T18:56:58.512Z",
    "TwampFwdDeltaMs":  0.32,
    "TwampRevDeltaMs":  0.94,
    "TwampProcDeltaMs": 0.18,
}

F) Forecast Insight API

Projected latency uses the last 5 minutes; forecasting interval and confidence level are computed from the last 10 minutes of latency data.

This API provides the latest forecasted measures using statistical based mean and projection.

Used with the /api/v1/forecast endpoint. You can add the agent_id and customer_id parameters:

curl -H "x-api-key: your_api_key_here" -s -k https://<analyzer_IP>:12099/api/v1/forecast?agent_id=<agentID>&customer_id=<customerID>

sample output:

{
    "agentID": "1",
    "time": "2024-06-21T18:56:58.512Z",
    "projectedLatencyMs": 1.5,
    "forecastingIntervalMs": 3.28,
    "confidenceLevel": 0
}

G) Radio Insight API

Latest snapshot uses the last 10 seconds; with time_range or chosen_time, data is returned for that custom window.

This API provides the latest radio/cellular measures.

Used with the /api/v1/radio endpoint. You can add the agent_id and customer_id parameters:

curl -H "x-api-key: your_api_key_here" -s -k https://<analyzer_IP>:12099/api/v1/radio?agent_id=<agentID>&customer_id=<customerID>

sample output:

{
    "CustomerID": "0",
    "agentID": "1",
    "time": "2025-02-04T17:12:56.062Z",
    "networkName": "Bell",
    "networkType": "4G LTE",
    "cellID": "40",
    "SINR_dB": "2.147489",
    "RSSI_dBm": "-63",
    "RSRP_dBm": "-10",
    "RSRQ_dB": "-94"
}

Optional: using the chosen_time parameter allows you to query data for a given time period, format start_time,end_time (ex: 2025-05-30T10:00:00Z,2025-06-15T17:00:00Z) The time specified has to be UTC, or the time zone configured for the analyzer (UTC by default)

curl -H "x-api-key: your_api_key_here" -k https://<analyzer_IP>:12099/api/v1/radio?customer_id=<customerID>&agent_id=<agentID&chosen_time=2025-07-07T16:12:26Z
2025-07-07T16:12:34Z

sample output:

[
  {
    "CustomerID": "0",
    "agentID": "12",
    "time": "2025-07-08T15:21:07.94Z",
    "ECIO_dB": "0",
    "PCI": "908",
    "RSRP_dBm": "-101",
    "RSRQ_dB": "-13",
    "RSSI_dBm": "0",
    "SINR_dB": "15.5",
    "cellID": "22938075680",
    "networkName": "TELUS",
    "networkType": "5G"
  },
  {
    "CustomerID": "0",
    "agentID": "12",
    "time": "2025-07-08T15:21:17.932Z",
    "ECIO_dB": "0",
    "PCI": "908",
    "RSRP_dBm": "-101",
    "RSRQ_dB": "-13",
    "RSSI_dBm": "0",
    "SINR_dB": "16",
    "cellID": "22938075680",
    "networkName": "TELUS",
    "networkType": "5G"
  },
]

H) Networks API

Lists customer IDs seen in the last 1 hour.

This API provides the customer_ids of the analyzer.

Used with the /api/v1/networks endpoint. You do not need any parameters

curl -H "x-api-key: your_api_key_here" -s -k https://<analyzer_IP>:12099/api/v1/networks

sample output:

{
  "count": 1,
  "customerId": [
    "0"
  ]
}

I) Agents API

Lists agents active in the last minute; metadata (if requested) comes from the last week.

This API provides the customer_ids of the analyzer.

Used with the /api/v1/agents endpoint. You can add the customer_id parameter and the optional metadata=true to also recieve the metadata for each agent:

curl -H "x-api-key: your_api_key_here" -s -k https://<analyzer_IP>:12099/api/v1/agents?customer_id=<customer_id>&metadata=true

sample output:

{
  "CustomerID": "0",
  "count": 1,
  "agents": [
    {
      "id": "9",
      "name": "Montreal ref",
      "networkName": "AzNet",
      "networkType": "Azure Server Network",
      "hardware": "Azure Server",
      "details": "Azure Agent uses for Testing plateform",
      "gpsPosition": "-43.8121,78.3522"
    }
  ]
}

J) Anomalies Insight API

Requires time_range or chosen_time; latency is aggregated in 30-second windows.

This API detects and reports network anomalies across protocols with detailed metrics including anomaly MAD (Median Absolute Deviation), packet drops, latency spikes, and anomaly distribution patterns.

Used with the /api/v1/anomalies endpoint. You can add the agent_id, customer_id, optional protocol (tcp, udp, http, https, icmp, twamp), and time_range (in seconds) parameters:

curl -H "x-api-key: your_api_key_here" -k -s "https://<analyzer_IP>:12099/api/v1/anomalies?agent_id=<agentID>&customer_id=<customerID>&protocol=tcp&time_range=3600"

sample output:

{
    "CustomerID": "0",
    "agentID": "1",
    "time": "2025-01-15T14:30:45.123Z",
    "tcp": {
        "anomaly_mad": 15.2,
        "drops": 3,
        "latency": 45.6,
        "anomaly_distribution": 8.9
    },
    "anomaliesDetected": true,
    "summary": "TCP protocol showing elevated anomaly indicators"
}

K) Performance Trends API

Compares mean latency from the last 1 hour to a baseline over the previous N days (default 7, ending yesterday).

This API analyzes agent performance trends over time, comparing current performance against historical baselines to identify degradation patterns and performance status.

Used with the /api/v1/trends endpoint. You can add the agent_id, customer_id, and optional lookback_days parameters:

curl -H "x-api-key: your_api_key_here" -k -s "https://<analyzer_IP>:12099/api/v1/trends?agent_id=<agentID>&customer_id=<customerID>&lookback_days=7"

sample output:

{
    "CustomerID": "0",
    "agentID": "1",
    "time": "2025-01-15T14:30:45.123Z",
    "currentLatency": 42.5,
    "baselineLatency": 35.2,
    "trendPercentage": 20.7,
    "status": "DEGRADED",
    "lookbackDays": 7
}

L) Health Report API

Aggregates mean latency over the report period: 1 day (daily), 7 days (weekly), or 30 days (monthly).

This API generates comprehensive network health reports with agent performance distribution, rankings, and actionable recommendations for network optimization.

Used with the /api/v1/health-report endpoint. You can add the customer_id, optional report_period (daily, weekly, monthly), and include_recommendations (true/false) parameters:

curl -H "x-api-key: your_api_key_here" -k -s "https://<analyzer_IP>:12099/api/v1/health-report?customer_id=<customerID>&report_period=daily&include_recommendations=true"

sample output:

{
    "CustomerID": "0",
    "reportPeriod": "daily",
    "generatedAt": "2025-01-15T14:30:45.123Z",
    "summary": {
        "totalAgents": 5,
        "healthDistribution": {
            "good": 3,
            "fair": 1,
            "poor": 1
        },
        "overallScore": 76.0
    },
    "agentDetails": [
        {
            "agentID": "1",
            "avgLatency": 25.3,
            "status": "GOOD"
        },
        {
            "agentID": "2", 
            "avgLatency": 65.8,
            "status": "FAIR"
        },
        {
            "agentID": "3",
            "avgLatency": 120.4,
            "status": "POOR"
        }
    ],
    "recommendations": [
        "5 total agents monitored",
        "3 agents performing well", 
        "1 agents need attention",
        "1 agents require immediate investigation",
        "Priority: Investigate agents with POOR status"
    ]
}

M) Agent Rankings API

Ranks agents using mean latency over time_range seconds (default 24 hours).

This API ranks all agents by performance metrics and trends, identifying top and bottom performers with detailed performance scores and comparative analysis.

Used with the /api/v1/agent-rankings endpoint. You can add the customer_id, optional metric (latency, stability, connectivity_health, overall), and time_range (in seconds) parameters:

curl -H "x-api-key: your_api_key_here" -k -s "https://<analyzer_IP>:12099/api/v1/agent-rankings?customer_id=<customerID>&metric=overall&time_range=86400"

sample output:

{
    "CustomerID": "0",
    "metric": "overall",
    "timeRangeSeconds": 86400,
    "generatedAt": "2025-01-15T14:30:45.123Z",
    "totalAgents": 5,
    "rankings": [
        {
            "agentID": "1",
            "avgLatency": 22.4,
            "performanceScore": 77.6,
            "rank": 1
        },
        {
            "agentID": "3",
            "avgLatency": 45.2,
            "performanceScore": 54.8,
            "rank": 2
        },
        {
            "agentID": "2",
            "avgLatency": 85.7,
            "performanceScore": 14.3,
            "rank": 3
        }
    ],
    "topPerformer": {
        "agentID": "1",
        "avgLatency": 22.4,
        "performanceScore": 77.6,
        "rank": 1
    },
    "bottomPerformer": {
        "agentID": "2",
        "avgLatency": 85.7,
        "performanceScore": 14.3,
        "rank": 3
    }
}

N) Correlation Analysis API

Analyzes latency over time_range seconds (default 2 hours), aggregated in 5-minute windows.

This API detects correlation patterns between agents to identify network-wide issues affecting multiple locations, with statistical correlation analysis and pattern classification.

Used with the /api/v1/correlation-analysis endpoint. You can add the customer_id, optional correlation_threshold (0.0-1.0), and time_range (in seconds) parameters:

curl -H "x-api-key: your_api_key_here" -k -s "https://<analyzer_IP>:12099/api/v1/correlation-analysis?customer_id=<customerID>&correlation_threshold=0.7&time_range=7200"

sample output:

{
    "CustomerID": "0",
    "time": "2025-01-15T14:30:45.123Z",
    "correlationThreshold": 0.7,
    "timeRangeSeconds": 7200,
    "totalAgentsAnalyzed": 4,
    "patternsFound": 2,
    "patterns": [
        {
            "description": "Agents showing similar latency degradation patterns",
            "affectedAgents": ["1", "2", "4"],
            "correlationStrength": 0.85,
            "patternType": "similar_degradation",
            "severity": "MEDIUM", 
            "recommendation": "Investigate shared network infrastructure - multiple agents affected similarly"
        },
        {
            "description": "Agents showing inverse latency patterns",
            "affectedAgents": ["3", "5"],
            "correlationStrength": 0.72,
            "patternType": "inverse_pattern", 
            "severity": "LOW",
            "recommendation": "Check for load balancing or failover behavior affecting different agents"
        }
    ]
}

O) Degradation Alerts API

Compares mean latency from the last 1 hour to a baseline over lookback_days days (default 3, ending yesterday).

This API proactively identifies agents showing performance degradation above configurable thresholds, with severity classification and detailed degradation analysis.

Used with the /api/v1/degradation-alerts endpoint. You can add the customer_id, optional severity_threshold (percentage), and lookback_days parameters:

curl -H "x-api-key: your_api_key_here" -k -s "https://<analyzer_IP>:12099/api/v1/degradation-alerts?customer_id=<customerID>&severity_threshold=20&lookback_days=3"

sample output:

{
    "CustomerID": "0",
    "time": "2025-01-15T14:30:45.123Z",
    "alertCount": 2,
    "severityThreshold": 20,
    "daysLookback": 3,
    "alerts": [
        {
            "agentID": "3",
            "degradationPercent": 45.2,
            "currentLatency": 78.5,
            "baselineLatency": 54.1,
            "severity": "HIGH",
            "message": "Agent 3 showing 45.2% performance degradation over 3 days"
        },
        {
            "agentID": "2", 
            "degradationPercent": 22.8,
            "currentLatency": 55.3,
            "baselineLatency": 45.0,
            "severity": "MEDIUM",
            "message": "Agent 2 showing 22.8% performance degradation over 3 days"
        }
    ]
}

P) iPerf Throughput Insight API

Returns the latest iPerf TCP and UDP throughput from the last 12 hours.

This API returns TCP and UDP throughput from iPerf measurements for a given QoSAgent.

Used with the /api/v1/iperf endpoint. You can add the agent_id and customer_id parameters:

curl -H "x-api-key: your_api_key_here" -s -k https://<analyzer_IP>:12099/api/v1/iperf?agent_id=<agentID>&customer_id=<customerID>

sample output:

{
    "CustomerID": "0",
    "agentID": "1",
    "time": "2026-06-15T14:59:46.207Z",
    "tcp": {
        "downloadThroughputMbps": 380.38,
        "uploadThroughputMbps": 246.02
    },
    "udp": {
        "downloadThroughputMbps": 120.5,
        "uploadThroughputMbps": 98.3
    }
}

API Definition

An API definition file complies with the OpenAPI standard is available in yml format.
You can download the file here:

wget https://api.latence.ca/software/latencetech_api_definition.yml

Troubleshooting

`customerID is required` or `agentID is required`.

It is possible, depending on the environement you use, that the analyzer part of the query needs to be in quotation marks:

curl -H "x-api-key: your_api_key_here" -s -k "https://<analyzer_IP>:12099/api/v1/ci?agent_id=<agentID>&customer_id=<customerID>"

Insight Open APIs

Introduction

Usage

Authentication

A) Connectivity Insight API

New connectivity insights v2

B) Throughput Insight API

C) Latency Insight API

D) Geoloc Insight API

E) Twamp Insight API

F) Forecast Insight API

G) Radio Insight API

H) Networks API

I) Agents API

J) Anomalies Insight API

K) Performance Trends API

L) Health Report API

M) Agent Rankings API

N) Correlation Analysis API

O) Degradation Alerts API

P) iPerf Throughput Insight API

API Definition

Troubleshooting

customerID is required or agentID is required.

`customerID is required` or `agentID is required`.