Skip to content

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 request aims to capture the latest available data from the last 5 minutes.

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 API requires that you open and secure the port 12099 on your analyzer instance.

Download

First, download the latencetech_api.yaml file using the following command:

wget https://api.latence.ca/software/latencetech_api.yaml

The latencetech_api.yaml is a docker compose file with the following contents:

version: '2.4'
services:
  latencetech_api:
    image: registry.latence.ca/software/latencetech_api:latest
    container_name: latencetech_api
    ports:
      - "12099:12099"
    extra_hosts:
      - "host.docker.internal:host-gateway"
    environment:
      - NODE_ENV=production
    restart: always
    volumes:
      - ${HOME}/.cached_lti_license_key:/root/.cached_lti_license_key

Launch

Launch the LatenceTech Insight API using docker compose:

docker compose -f latencetech_api.yaml pull
docker compose -f latencetech_api.yaml up -d

The container should be deployed on the VM onto which you have an analyzer installed.

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

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.

B) Throughput Insight API

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

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 ,https, httpss, 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

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

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

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

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

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

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

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

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

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

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

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

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 days_lookback 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&days_lookback=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"
        }
    ]
}

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