Skip to main content

EDR Agent Health API (localhost)

Nick
  • Updated

Team: Huntress Managed Endpoint Detection and Response (EDR)
Product: Agent Health API
Environment: Windows (macOS in progress)
Summary:The client-side EDR Agent API provides a local web endpoint on your systems (via localhost), allowing you to easily check the health, service status, versions, and connectivity of the Huntress agent via a simple web request.

Understanding Your Endpoint's Health with the EDR Agent API

To provide greater transparency and empower our customers and partners, we've introduced a local web endpoint within our EDR (Endpoint Detection and Response) agent. This feature, known as the client-side EDR Agent API, offers a simple way to gather real-time insights into the operational status of the agent directly on your systems.

What is the Client-Side EDR Agent API?

Upon installation of the EDR agent, a local-only web server automatically starts on the endpoint. This server hosts an API that allows you to query the health and status of the running agent and its components. While this API starts automatically, it can be disabled if necessary through a configuration change managed by our EDR engineering team. We are actively working to make this a self-service account configuration option in the near future.

How Can You Use It?

To access this information, you'll need to execute a script or utilize code to make a web request to the Huntress agent. This can be accomplished using various scripting languages. Common methods include PowerShell on Windows and bash on macOS.

The API endpoint is located at the following address:

http://localhost:24799/health

As long as the HuntressUpdater service is installed and running, this endpoint will be active and will return output when queried.

 

Example using PowerShell:

Invoke-RestMethod -Uri "http://localhost:24799/health" | ConvertTo-Json

 

Example using Bash:

Please note the macOS implementation of this feature isn't quite complete but you can preview it using the curl command similar to the below. This first command is easier to read but more difficult to automate, while the shorter command is the opposite.

curl --json '{"tool": "curl"}' http://localhost:24799/health | jq

The exact command you'll use will vary based on how you implement it. If in doubt, starting with a simpler command such as below may make implementation easier.

curl http://localhost:24799/health

RMM / ImmyBot example

Place this immediately after the existing PowerShell/Bash examples.

#### Example: Using the Health API from an RMM (ImmyBot)

Many partners retrieve Health API data from an RMM such as ImmyBot by running a simple PowerShell line like:

```powershell
Invoke-RestMethod -Uri "http://localhost:24799/health"
markdown

This returns the full Health API response, but if your script only reads the status field, your report or dashboard will only know whether the agent is “Healthy” or “Degraded”.

On Windows, tools like ImmyBot run that line in a PowerShell step. You can safely extend that script instead of replacing it by returning a custom object that includes both status and the key connectivity timestamps:

$health = Invoke-RestMethod -Uri "http://localhost:24799/health" -TimeoutSec 5

[pscustomobject]@{
    ComputerName = $env:COMPUTERNAME      # keep or replace with your existing ID field
    Status       = $health.status         # what you already have today
    Events       = $health.connectivity.events
    Errors       = $health.connectivity.errors
    Survey       = $health.connectivity.survey
    Tasks        = $health.connectivity.tasks
    Update       = $health.connectivity.update
}
powershell

Your RMM will see one object per endpoint with these properties. When you export to CSV/XLSX or build a dashboard, you’ll still have the same ComputerName and Status columns you already use, plus new columns for Events, Errors, Survey, Tasks, and Update. This lets you distinguish between truly unhealthy agents and cases where status = degraded is driven by stale or missing telemetry instead of an actual service failure.

Note: Many monitoring scripts only read status from the Health API. This works for basic “healthy vs degraded” checks, but can generate noisy alerts when status = degraded for state or telemetry reasons. Exposing the connectivity timestamps alongside status lets you apply richer logic and reduce false positives.

---

### 2) New subsection under “Interpreting the API Output” – degraded vs connectivity table

**Place this right after the existing description of the `Connectivity` fields.**

```markdown
#### Using connectivity timestamps to interpret “Degraded”

When you expose the connectivity fields (`errors`, `events`, `survey`, `tasks`, `update`) alongside `status`, you can tell whether a “Degraded” status represents a real agent problem or just a bookkeeping/state issue.

The table below shows example patterns and how to interpret them:

| Status + Connectivity Pattern                                                                                                       | Likely Meaning                                                                                                                                                         | Next Steps                                                                                                                                                                                        |
|-------------------------------------------------------------------------------------------------------------------------------------|------------------------------------------------------------------------------------------------------------------------------------------------------------------------|---------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------|
| `status = healthy` and all connectivity timestamps are recent                                                                       | Agent is running normally and checking in as expected.                                                                                                                 | No action needed.                                                                                                                                                                                |
| `status = degraded`, `events` is a normal recent timestamp, other connectivity timestamps are recent                               | Rio is running and successfully sending Process Insights data. “Degraded” is likely driven by another factor (for example, a transient service state that has cleared). | Review services and logs if you see ongoing issues. Otherwise, treat the endpoint as healthy once your tooling confirms recent connectivity.                                                    |
| `status = degraded`, `events = 0001-01-01T00:00:00Z` but `survey`, `tasks`, and `update` timestamps are recent and data is visible in the Huntress portal | The endpoint is talking to Huntress and the agent is working, but the `events` timestamp is invalid or never populated. This is usually a local telemetry/state issue rather than a broken Rio instance. | Treat this as a low-priority state issue. If it persists or you see impact in the portal, contact Huntress Support for deeper investigation.                                                   |
| `status = degraded` and all connectivity timestamps are stale, with no recent data visible in the Huntress portal                  | The agent is not checking in correctly and telemetry is stale. This indicates a truly unhealthy agent that needs remediation.                                         | Follow the troubleshooting steps below (services, network/firewall, reinstall/repair). If the agent cannot re-establish connectivity, reach out to Huntress Support for further assistance.     |
 

Interpreting the API Output

The output from the API is structured for easy understanding and can be readily parsed by scripts for automated data extraction. Here's a breakdown of the information you'll find on a healthy system:

Let's delve into each section:

  • Status: This field provides a straightforward answer to the question: "Is the Huntress EDR running correctly?" It will display either "Healthy" or "Degraded". A "Degraded" status indicates an issue with the EDR deployment on that specific machine. (See the Troubleshooting section below for more details).
  • Services: This section lists all the installed EDR services on the endpoint and their current status as reported by the local service manager. Possible states include "running", "stopped", or “missing”.
  • Versions: Here, you'll find the version numbers for the various Huntress components installed on the system. This information is valuable for ensuring your deployment is up-to-date.
  • Connectivity: This section displays the last successful communication timestamps for key EDR components with our backend servers.
    • "errors": refers to agent roadblocks like connection or service/process errors from HuntressUpdater
    • "events": represents the last time an EDR survey was uploaded by Rio. This data is used to populate Process Insights pages in your Huntress portal.
    • "survey": represents the last time a survey was uploaded by HuntressAgent. This data is used to populate the endpoints info in your Huntress portal.
    • "tasks": the last time the HuntressAgent ran a task initiated by the Huntress portal.
    • "update": the last time the HuntressUpdater checked for a new update.

Troubleshooting Common Issues

Here's a guide to interpreting the API output and addressing potential problems:

  • The "Status" is showing as "degraded"

    • Examine the other sections of the output for any immediate clues, such as stopped services.
    • If the cause remains unclear, collect the local Huntressagent logs from a path like "C:\Program files\Huntress\HuntressAgent.log" and reach out to our Support team via Support@Huntress.com.
    • If you are pulling `status` and the full `connectivity` block into an RMM or script, see the “Using connectivity timestamps to interpret ‘Degraded’” table above for examples of how to distinguish transient or bookkeeping issues from truly unhealthy agents before taking action.

  • One or more of the services is showing a "stopped" state:

    • Investigate if other security tools on the endpoint might be interfering with the EDR components. Allow List Huntress in Third Party Security Software. 
    • Verify that the recommended exclusions for our binaries and network paths are properly configured within your security solutions.
    • Reboot to clear any file locks that could be preventing updates. If that fails, please reach out to our Support team.

  • One of the versions is empty or missing:

    • If the endpoint is running an older operating system (pre-Windows 8/pre-Server 2012), the "Rio" and "Huntmon" components will not be present and will therefore be missing from the list.  The status will be in “degraded”.

  • One or more of the dates are missing from the "Connectivity" section:

    • This typically indicates a network connectivity problem on the endpoint or its network. Please ensure there is no network proxy in place (Huntress is incompatible with most proxies), no DNS blocks preventing access to our services, no blocking of port 443 outbound, no certificate interception/pinning service, and no other security tools on the endpoint that could be blocking the Huntress components from communicating with the internet.
    • Alternatively this can indicate the corresponding service is not running. I.E. if the timestamp for "survey" is 0001-01-01 that typically means the HuntressAgent service is not running. 
    • When a connectivity timestamp is `0001-01-01T00:00:00Z`, it typically means that value has never been populated. If other connectivity timestamps are recent and you see data in the Huntress portal, treat this as a state/telemetry mismatch rather than assuming the agent is offline. Combine the connectivity timestamps and what you see in the Huntress portal (as shown in the table above) before taking disruptive remediation actions such as bulk reinstalls or forced reboots.

  • You are receiving a "Invoke-RestMethod : Unable to connect to the remote server" prompt:

    • This typically indicates that the Huntress Updater Service (HuntressUpdater) is not running/started. Reboots will often fix this as it resolves conflicts and releases file locks.
    • You can try the following command to start up the service (run in the SYSTEM user context)

    Windows PoSh/CMD

    sc.exe start HuntressUpdater

    macOS Bash

    sudo launchctl enable system/com.huntress.HuntressUpdater
    sudo launchctl kickstart system/com.huntress.HuntressUpdater

    Linux Bash

    sudo systemctl enable --now huntress-updater.service

     

    We hope this information empowers you to better understand the health and connectivity of the Huntress EDR agent on your endpoints. If you have any questions or require further assistance, please don't hesitate to contact our support team support@huntress.com 

Related articles