DescribeAgents
Lists agents or connectors as specified by ID or other filters. All agents/connectors
associated with your user account can be listed if you call DescribeAgents
as is
without passing any parameters.
Request Syntax
{
"agentIds": [ "string
" ],
"filters": [
{
"condition": "string
",
"name": "string
",
"values": [ "string
" ]
}
],
"maxResults": number
,
"nextToken": "string
"
}
Request Parameters
For information about the parameters that are common to all actions, see Common Parameters.
The request accepts the following data in JSON format.
- agentIds
-
The agent or the Connector IDs for which you want information. If you specify no IDs, the system returns information about all agents/Connectors associated with your AWS user account.
Type: Array of strings
Required: No
- filters
-
You can filter the request using various logical operators and a key-value format. For example:
{"key": "collectionStatus", "value": "STARTED"}
Type: Array of Filter objects
Required: No
- maxResults
-
The total number of agents/Connectors to return in a single page of output. The maximum value is 100.
Type: Integer
Required: No
- nextToken
-
Token to retrieve the next set of results. For example, if you previously specified 100 IDs for
DescribeAgentsRequest$agentIds
but setDescribeAgentsRequest$maxResults
to 10, you received a set of 10 results along with a token. Use that token in this query to get the next set of 10.Type: String
Required: No
Response Syntax
{
"agentsInfo": [
{
"agentId": "string",
"agentNetworkInfoList": [
{
"ipAddress": "string",
"macAddress": "string"
}
],
"agentType": "string",
"collectionStatus": "string",
"connectorId": "string",
"health": "string",
"hostName": "string",
"lastHealthPingTime": "string",
"registeredTime": "string",
"version": "string"
}
],
"nextToken": "string"
}
Response Elements
If the action is successful, the service sends back an HTTP 200 response.
The following data is returned in JSON format by the service.
- agentsInfo
-
Lists agents or the Connector by ID or lists all agents/Connectors associated with your user account if you did not specify an agent/Connector ID. The output includes agent/Connector IDs, IP addresses, media access control (MAC) addresses, agent/Connector health, host name where the agent/Connector resides, and the version number of each agent/Connector.
Type: Array of AgentInfo objects
- nextToken
-
Token to retrieve the next set of results. For example, if you specified 100 IDs for
DescribeAgentsRequest$agentIds
but setDescribeAgentsRequest$maxResults
to 10, you received a set of 10 results along with this token. Use this token in the next query to retrieve the next set of 10.Type: String
Errors
For information about the errors that are common to all actions, see Common Errors.
- AuthorizationErrorException
-
The AWS user account does not have permission to perform the action. Check the IAM policy associated with this account.
HTTP Status Code: 400
- HomeRegionNotSetException
-
The home region is not set. Set the home region to continue.
HTTP Status Code: 400
- InvalidParameterException
-
One or more parameters are not valid. Verify the parameters and try again.
HTTP Status Code: 400
- InvalidParameterValueException
-
The value of one or more parameters are either invalid or out of range. Verify the parameter values and try again.
HTTP Status Code: 400
- ServerInternalErrorException
-
The server experienced an internal error. Try again.
HTTP Status Code: 500
Examples
Describe agents that are running
The following example describes all agents that are currently running by passing
object array values to the parameter filters
where condition
is
"EQUALS", name
is "health", and value
is "RUNNING". This results
in a descriptive response that lists all agents running in your account.
Sample Request
{
"filters": [
{
"condition": "EQUALS",
"name": "health",
"values": [ "RUNNING" ]
}
]
}
Sample Response
{
"agentsInfo": [
{
"agentId": "o-55vu6xeo8zs27b905",
"hostName": "ip-172-31-24-158.us-west-2.compute.internal",
"agentNetworkInfoList": [
{
"ipAddress": "172.31.24.158",
"macAddress": "02:7C:B6:F7:82:C4"
}
],
"version": "2.0.1008.0",
"health": "RUNNING",
"lastHealthPingTime": "2018-03-19T22:48:25Z",
"collectionStatus": "STARTED",
"agentType": "ONPREMISES",
"registeredTime": "2018-01-30T18:54:19Z"
},
{
"agentId": "o-5i6fq7z1fhgokgreg",
"hostName": "win-gv9i8gpt9t1",
"agentNetworkInfoList": [
{
"ipAddress": "192.168.204.1",
"macAddress": "00:50:56:C0:00:01"
},
{
"ipAddress": "192.168.64.1",
"macAddress": "00:50:56:C0:00:08"
},
{
"ipAddress": "172.31.12.174",
"macAddress": "0A:84:BB:BF:88:8E"
}
],
"version": "2.0.1008.0",
"health": "RUNNING",
"lastHealthPingTime": "2018-03-19T22:29:33Z",
"collectionStatus": "STARTED",
"agentType": "ONPREMISES",
"registeredTime": "2018-03-16T23:54:19Z"
}
]
}
See Also
For more information about using this API in one of the language-specific AWS SDKs, see the following: