> For the complete documentation index, see [llms.txt](https://docs.thousandeyes.com/llms.txt). Markdown versions of documentation pages are available by appending `.md` to page URLs; this page is available as [Markdown](https://docs.thousandeyes.com/product-documentation/global-vantage-points/endpoint-agents/managing/endpoint-agent-health.md).

# Endpoint Agent Health

Endpoint Agent Health helps you understand whether an Endpoint Agent can collect telemetry and run tests. Instead of showing only that an agent is registered, the ThousandEyes platform reports the agent's health state, the reason for that state, the impact, and the recommended action.

Agent Health details are available in **Endpoint Experience > Agent Settings**. You can also export the information for support and access the same fields through external APIs.

{% hint style="info" %}
Agent Health is supported on Endpoint Agents running on Android, Windows, and macOS. The feature requires Endpoint Agent version 2.57.0 or later and Mobile Endpoint Agent version 1.8.2 or later.
{% endhint %}

## Prerequisites

To view Endpoint Agent settings and generate support bundles, you need a ThousandEyes account with the required admin permissions.

## Understanding Agent Health

For each agent, Agent Health reports the following information:

| Information        | Description                                                                                                                        |
| ------------------ | ---------------------------------------------------------------------------------------------------------------------------------- |
| State              | The current health state of the agent. Supported states include **Active**, **Inactive**, **Degraded**, and **DeploymentFailed**.  |
| Reason             | A human-readable explanation and, where available, a stable reason code for the blocker.                                           |
| Impact             | The telemetry or agent function that might be unavailable, such as test scheduling, telemetry collection, or network context.      |
| Recommended action | The remediation that addresses the reported blocker.                                                                               |
| Evidence           | Bounded, timestamped checks and key fields that support the reported state. Agent Health does not expose unrestricted device logs. |
| Health history     | A per-agent record of health-state changes that helps you identify when an issue started.                                          |

The state describes the overall condition, while the reason and impact explain what needs attention. An agent can be registered with the ThousandEyes platform and still report an issue that prevents it from running tests or collecting some telemetry.

## Viewing Agent Health

1. In the ThousandEyes platform, go to **Endpoint Experience > Agent Settings**.
2. Select an agent.

   The agent details panel opens. Any current Agent Health findings appear at the top of the panel. Each finding includes the state, the reason, the impact, and an action.

![Endpoint Agent details panel showing degraded health findings with impacts and actions](https://1112912342-files.gitbook.io/~/files/v0/b/gitbook-x-prod.appspot.com/o/spaces%2F-M4QARF6s57qxMrOHDTZ%2Fuploads%2Fgit-blob-7e21571371773b5596b622d76adbed87ae58773f%2Fendpoint-agent-explainability-health-findings.png?alt=media)

3. Review the reported action and correct the relevant device, operating system, mobile device management (MDM), or original equipment manufacturer (OEM) configuration.
4. Return to the agent details panel and confirm that the current findings and state reflect the change.

{% hint style="info" %}
The information available depends on the agent platform and whether the agent can check in with the ThousandEyes platform. Some fields might be unavailable when the agent cannot report the required evidence.
{% endhint %}

## Reviewing Common Health Reasons

Agent Health uses stable reason codes for common blockers. The following reason codes are included in the current feature definition:

| Reason code                                           | State    | Reported condition                                                                      |
| ----------------------------------------------------- | -------- | --------------------------------------------------------------------------------------- |
| **ACCESS\_BACKGROUND\_LOCATION\_PERMISSION\_MISSING** | Degraded | Background location permission is missing.                                              |
| **ACCESS\_FINE\_LOCATION\_PERMISSION\_MISSING**       | Degraded | Precise location permission is missing.                                                 |
| **APP\_IN\_STANDBY\_BUCKET\_RESTRICTED**              | Degraded | App activity is restricted in standby.                                                  |
| **BACKGROUND\_EXECUTION\_RESTRICTED**                 | Degraded | Background activity is restricted.                                                      |
| **BATTERY\_OPTIMIZATION\_ENABLED**                    | Degraded | Battery optimization is enabled.                                                        |
| **CHROME\_OS\_FOREGROUND\_SERVICE\_NOT\_RUNNING**     | Degraded | The ChromeOS foreground service is not running.                                         |
| **DEVICE\_NOT\_FULLY\_MANAGED**                       | Degraded | The device is not fully managed.                                                        |
| **LOCATION\_SERVICES\_DISABLED**                      | Degraded | Location services are turned off.                                                       |
| **MDM\_POLICY\_RESTRICTING\_AGENT**                   | Degraded | An MDM policy might be restricting the agent.                                           |
| **MISSING\_REQUIRED\_PERMISSIONS**                    | Degraded | Required permissions are missing.                                                       |
| **OEMCONFIG\_APPLY\_FAILED**                          | Degraded | OEMConfig settings could not be applied.                                                |
| **OEMCONFIG\_INCOMPATIBLE\_VERSION**                  | Degraded | The installed OEMConfig application is incompatible with the device's operating system. |
| **OEMCONFIG\_NOT\_INSTALLED**                         | Degraded | The device manufacturer's OEMConfig application is not installed.                       |
| **READ\_PHONE\_STATE\_PERMISSION\_MISSING**           | Degraded | Phone state permission is missing.                                                      |
| **SCHEDULE\_EXACT\_ALARM\_NOT\_ALLOWED**              | Degraded | Exact alarm scheduling is not granted.                                                  |
| **SCHEDULER\_NOT\_RUNNING**                           | Degraded | Agent check-in is overdue.                                                              |
| **SERVICE\_THROTTLED\_OR\_KILLED**                    | Degraded | The agent service was limited or stopped.                                               |
| **UNKNOWN**                                           | Degraded | A diagnostic check failed unexpectedly.                                                 |

The platform might report a different reason when evidence changes. Use the current reason, impact, and recommended action as the source of truth for the agent's current condition.

## Reviewing Deployment and Enrollment Details

For Mobile Endpoint Agents on Android, the agent details panel can include deployment and enrollment information such as:

* Install method.
* Install source.
* Management mode.
* MDM vendor.
* Whether OEMConfig is installed.
* Whether OEMConfig is applied.

This information helps you distinguish a registration problem from a device-management or OEM configuration problem. For example, an agent might register successfully while OEMConfig is not installed or has not been applied.

![Endpoint Agent details panel showing deployment and enrollment and device details](https://1112912342-files.gitbook.io/~/files/v0/b/gitbook-x-prod.appspot.com/o/spaces%2F-M4QARF6s57qxMrOHDTZ%2Fuploads%2Fgit-blob-23b7a01e2e50fffac122c90630abbad039d0bb86%2Fendpoint-agent-explainability-deployment-details.png?alt=media)

{% hint style="warning" %}
Deployment and enrollment details are not available for Endpoint Agents on Windows and macOS. Agent Health still reports supported health information for those platforms. MDM Vendor information is not currently available for ChromeOS devices.
{% endhint %}

The **Deployment and Enrollment** section is available only for Mobile Endpoint Agents that were deployed and registered after October 1st, 2026. If you installed the Mobile Endpoint Agent on a device before that date, the section does not appear until you re-enroll the agent. Choose the method that matches how you manage the device.

### Re-enrolling a Mobile Endpoint Agent

{% tabs %}
{% tab title="Clear App Data" %}

1. In the Mobile Endpoint Agent app, open **Settings**.
2. Select **Clear app data**.

   This action deregisters the agent.
3. Register the agent again by using your MDM configuration or scanning the registration QR code.
   {% endtab %}

{% tab title="MDM-Managed Device" %}

1. Close the app from the recent apps screen by swiping it away.
2. Reopen the app.

   The agent registers again if the configuration or connection string is still valid.
3. If the configuration or connection string is no longer valid, use your MDM to send a fresh configuration with a valid connection string, then launch the app.
   {% endtab %}

{% tab title="Manual Registration" %}

1. Scan the registration QR code again on the device.

   The agent registers again.
   {% endtab %}
   {% endtabs %}

## Viewing Onboarding Health History

Onboarding Health History records changes to an agent's onboarding health state.

1. Open the agent details panel from **Endpoint Experience > Agent Settings**.
2. Scroll to **Device Details**.
3. Select **View Onboarding Health History**.

   The dialog lists health findings with their state, reason, timestamp, summary, impact, and action. Expand a finding to view its details.

![Onboarding Health History dialog showing degraded findings with timestamps, impacts, and actions](https://1112912342-files.gitbook.io/~/files/v0/b/gitbook-x-prod.appspot.com/o/spaces%2F-M4QARF6s57qxMrOHDTZ%2Fuploads%2Fgit-blob-3aa65976b4384755f87f8a00882fce01619ce681%2Fendpoint-agent-explainability-onboarding-history.png?alt=media)

Use the history to determine when a permission, scheduling, battery, OEMConfig, or other configuration issue first appeared. The history reports the agent's observed changes; it does not change the device configuration.

## Using Agent Health for Troubleshooting

Use the following workflow when an agent is registered but does not behave as expected:

1. Confirm that the agent runs a supported version.
2. Open the agent in **Endpoint Experience > Agent Settings**.
3. Read the current state and reason before collecting raw device logs.
4. Review the impact to determine whether the issue affects test scheduling, telemetry collection, location or Wi-Fi context, service execution, or another supported capability.
5. Apply the recommended action on the device or in the relevant MDM, OEM, firewall, or operating system configuration.
6. Review the agent's current state and **Onboarding Health History** to confirm whether the finding changes.
7. If the issue persists, include the Agent Health report in the support bundle or provide the Agent Health fields through your external API workflow.

Agent Health reduces the need to infer the cause from an agent's registered status or from unstructured logs. It does not remove the need to check the device or its management configuration when the recommended action requires a device-side change.

## Exporting Agent Health Details

Agent Health details are available through the following support workflows:

* Support bundles can include an Agent Health report with the state, reason, impact, and health history.
* External APIs expose the same Agent Health fields for downstream troubleshooting and automation.

The available fields depend on the agent platform and the evidence that the agent can collect. Treat unavailable fields as unavailable data, not as proof that the corresponding device condition is clear.

## Understanding Platform Differences

Mobile Endpoint Agents collect a different set of telemetry from desktop Endpoint Agents. Agent Health identifies platform limitations and missing signals where they affect agent health or the collected data.

For example, mobile agents might report missing permissions, blocked background execution, unavailable exact alarm scheduling, OEMConfig problems, or service termination. Desktop agents provide a different set of operating-system and service signals. The platform-specific data model does not mean that every health reason is available on every platform.

## Related Articles

* [Manage Endpoint Agent Settings](https://docs.thousandeyes.com/product-documentation/global-vantage-points/endpoint-agents/managing/manage-endpoint-agent-settings)
* [Mobile Endpoint Agent Installation on Android Devices](https://docs.thousandeyes.com/product-documentation/global-vantage-points/endpoint-agents/installing/mobile-endpoint-agent/android/mepa_android)
* [Data Collected by Endpoint Agent](https://docs.thousandeyes.com/product-documentation/global-vantage-points/endpoint-agents/data-collected-by-endpoint-agent)
* [Troubleshooting Endpoint Agent Issues](https://docs.thousandeyes.com/product-documentation/end-user-monitoring/troubleshooting/troubleshooting-endpoint-agent-issues)
