| Developer Documentation
Documentation
Support SiteRoadmapStatus PagePrivacy

How to check if an Agent is online

Determine an agent's live connection status.

This guide explains how to determine whether an agent is currently online using fields retrieved from the Agent or AgentList endpoints, and provides details on the logic the Fleet Manager uses to show the green/grey status icon in the Devices list.

What defines "online"?

In the IXON Portal, an agent is considered online when at least one of the following fields on the Agent is populated:

  • activeVpnSession: if the object is populated, the Agent can communicate with the VPN Server.
  • mdrServer: if the object is populated, the Agent can communicate with the MQTT server it is connected to.
📘

Always query activeVpnSession and mdrServer with their subfields!

The reliable way to read these fields is to request their subfields and check the content inside, rather than testing the bare top-level field for null. There are two reasons:

  • activeVpnSession has no default publicId or name (the fields most endpoints return by default). So if you request only the bare field activeVpnSession, the API returns an empty object {} when a session exists and null when it does not. An opaque {} is easy to misread and tells you nothing about the session — you cannot see which server it is on, its VPN
    address, or whether it has been closed.
  • mdrServer does return publicId and name by default, but for a consistent approach you should inspect its contents the same way.

Request the contents of both objects

Request the subfields of both activeVpnSession and mdrServer. Use activeVpnSession.rscServer.* to expand the VPN server object, and name the other session subfields explicitly.

curl --request GET \
  --url 'https://portal.ixon.cloud/api/agents/<your_agent_id>?fields=publicId,name,activeVpnSession.rscServer.*,activeVpnSession.rscServer.location.*,activeVpnSession.startedOn,activeVpnSession.sessionName,activeVpnSession.vpnAddress,activeVpnSession.closed,mdrServer.publicId,mdrServer.name' \
  --header 'Api-Version: 2' \
  --header 'Api-Application: <your_application_id>' \
  --header 'Api-Company: <your_company_id>' \
  --header 'Accept: application/json' \
  --header 'Authorization: Bearer <your_bearer_token>'

A fully populated response (both the VPN session and the MDR/MQTT server are up):

{
  "type": "Agent",
  "data": {
    "publicId": "ay403xfX4zGi",
    "name": "IXrouter 3",
    "activeVpnSession": {
      "rscServer": {
        "publicId": "IRQlG8gu1gai",
        "name": "NL Amsterdam RSV server #4",
        "vpnRange": "10.187.0.0/16",
        "supportedLayers": ["tun", "tap"],
        "location": {
          "name": "Amsterdam",
          "latitude": "52.374000",
          "longitude": "4.889700"
        }
      },
      "startedOn": "2026-05-12T23:08:36Z",
      "sessionName": "SID-AY403XFX4ZGI.AGENTS-[OPENVPN_L2]-91948",
      "vpnAddress": "10.187.114.108",
      "closed": false
    },
    "mdrServer": {
      "publicId": "xPlPVw5qa78v",
      "name": "NL Amsterdam MDI server #1"
    }
  },
  "status": "success"
}

Decide online status from the contents

Read online/offline from whether each object has content inside. For example, an agent whose VPN is up but whose MDR/MQTT server is not yet connected looks like this — activeVpnSession is populated, mdrServer is null, so the agent is online:

"activeVpnSession": {
  "rscServer": { "publicId": "IRQlG8gu1gai", "name": "NL Amsterdam RSV server #4" },
  "vpnAddress": "10.187.114.108",
  "closed": false
},
"mdrServer": null

Python code implementation

For a basic Python implementation, check out the tutorial below.

Online is not the same as "ready to push configuration"

Being online is a "weaker" condition than being able to push a configuration. Pushing configuration additionally requires the MDR/MQTT connection (mdrServer) and the previous configuration to be in sync. If that is your use case, check How to push a configuration to an agent.

Related


Updated about 1 hour ago

Did this page help you?