---
updatedAt: 2026-07-28T13:00:53.000Z
agentTools:
  projectIndex: https://developer.ixon.cloud/llms.txt
---

# 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](https://developer.ixon.cloud/reference/get_agents-publicid) or [AgentList](https://developer.ixon.cloud/reference/get_agents) 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.

<Callout icon="📘" theme="info">
  ### 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&#x20;**`{}`**&#x20;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.
</Callout>

## 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
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):

```json
{
  "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**:

```json
"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.

<Recipe slug="how-to-verify-an-agents-status-onlineoffline-in-pure-python" title="How to verify an agent's status (online/offline) in pure Python" />

## 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 <Anchor target="_blank" href="https://developer.ixon.cloud/docs/how-to-push-a-configuration-to-an-agent">**How to push a configuration to an agent**</Anchor>.

## Related

* [Agent endpoint reference](https://developer.ixon.cloud/reference/get_agents-publicid)
* [AgentList endpoint reference](https://developer.ixon.cloud/reference/get_agents)

<br />