---
title: "system.eam.queryAgentStatus"
description: "Returns the current state of the matching agents."
---

# system.eam.queryAgentStatus

> Returns the current state of the matching agents.

This function is used in **Python Scripting**.

## Description
Returns the current state of the matching agents. This function can only be called from the Controller.

## Client Permission Restrictions
This scripting function has no [Client Permission](../../../ignition-modules/vision/vision-project-properties/vision-project-properties.md#vision-permissions-properties) restrictions.

## Syntax
`system.eam.queryAgentStatus(groupIds, agentIds, isConnected)`

### Parameters
Type | Parameter | Description 
------- | ------- | -----
List| `groupIds` | A list of groups to restrict the results to. If not specified, all groups will be included.
List| `agentIds` | A list of agent names to restrict the results to. If not specified, all agents will be allowed.
Boolean| `isConnected` | If True, only returns agents that are currently connected. If False, only agents that are considered down will be returned, and if not specified, all agents will be returned.

### Returns
**Dataset** - A dataset with columns AgentName, NodeRole, AgentGroup, LastCommunication, IsConnected, IsRunning, RunningState, RunningStateInt, LicenseKey, and Version, where each row is a new agent.

:::note 
Possible values for RunningState and RunningStateInt are: 0 = Disconnected, 1 = Running, 2 = Warned, 3 = Errored
:::
    
### Scope
Gateway, Vision Client, Perspective Session

## Code Examples
```python title="Example #1 - Querying Agent Status Information"
# This script will loop through each row of the dataset and grab out every value from that row and assign it to a matching variable. Those variables can then be used in some way.
results=system.eam.queryAgentStatus()
for row in range(results.rowCount):
    agentName=results.getValueAt(row, "AgentName")
    nodeRole=results.getValueAt(row, "NodeRole")
    agentGroup=results.getValueAt(row, "AgentGroup")
    lastComm=results.getValueAt(row, "LastCommunication")
    isConnected=results.getValueAt(row, "IsConnected")
    isRunning=results.getValueAt(row, "IsRunning")
    runningState=results.getValueAt(row, "RunningState")
    runningStateInt=results.getValueAt(row, "RunningStateInt")
    licenseKey=results.getValueAt(row, "LicenseKey")
    platformVersion=results.getValueAt(row, "Version")
    # Can include some code here to use the variables in some way for each row like printing each variable to the console.
```
```python title="Example #2 - Querying Agent Status Information"
# This script will grab status information from agents called Agent1, Agent2, Agent3, and will then place the data into a table on the same window.
results=system.eam.queryAgentStatus(agentIds=["Agent1", "Agent2", "Agent3"])
event.source.parent.getComponent('Table').data = results
```