ShowAgentList · Customer Self-Service

Displays all the agents.

Results can be filtered by endpoint name, endpoint type and IP range.

HTTP Request

PUT /WebApp/OSCE_iES/OsceIes/ApiEntry

Parameters

Important:

The HTTP request body must contain all required parameters.

Name	Type	Description
Required Parameters
Url	String	Specifies the Endpoint Sensor API request to query
TaskType	Integer	Type of API request For Endpoint Sensor, the value is always `4`. For available values, see Threat Investigation API Task Types.
Payload	Object	Payload of the request
Optional Parameters
Payload.pagination.offset	Integer	Page where to start retrieving records
Payload.pagination.limit	Integer	Number of records to retrieve
filter	Object array	Container for `filter` objects
filter[i].type	Integer	Type of filter to use For possible values, see Threat Investigation API Filter Values.
filter[i].value	String array	Filter value For possible values, see Threat Investigation API "selectAll" Types and Values.

HTTP Request Example

PUT /WebApp/OSCE_iES/OsceIes/ApiEntry

HTTP Request Body

Specify a JSON object containing the following HTTP request body:

Request body:

Example 1: Request agents without specifying a filter

{
  "Url": "V1/Task/ShowAgentList",
  "TaskType": 4,
  "Payload": {
    "pagination": {
      "offset": 0,
      "limit": 50
    },
    "filter": []
  }
}

Example 2: Request the agents with the specified endpoint name filter

{
  "Url": "V1/Task/ShowAgentList",
  "TaskType": 4,
  "Payload": {
    "pagination": {
      "offset": 0,
      "limit": 50
    },
    "filter": [{
      "type": 1,
      "value": "a"
    }]
  }
}

Example 3: Request the agents which match the filter criteria (IP range from 10.0.0.0 to 10.0.1.0).

{
  "Url": "V1/Task/ShowAgentList",
  "TaskType": 4,
  "Payload": {
    "pagination": {
      "offset": 0,
      "limit": 50
    },
    "filter": [{
        type: 4,
        value: ["10.0.0.0", "10.0.1.0"]
    }]
  }
}

Note:

Specifying an IP range as the criteria may return results that do not include newly registered agents. If the new agents do not appear during the first request, allow some time for the server to synchronize IP information before sending another request.

Response

If successful, this method returns an HTTP status code of "200", result code of "0", and a response body with the following structure:

{
  "Data": {
    "Code": 0,
    "CodeType": 1,
    "Message": "OK",
    "Data": {
      "taskId": "",
      "lastContentId": "",
      "hasMore": false,
      "serverGuid": "",
      "serverName": "",
      "content": [
        {
          "statusCode": 0,
          "message": "Success",
          "content": {
            "agentEntity": [
              {
                "agentGuid": 
                 "da73261e-f01e-407e-bf5d-b5d65e3a4300",
                "serverGuid": 
                 "A7FF3BD2-C7A4-4455-9F18-6A282D89EF27",
                "machineName": "JERRY-OSCE88",
                "isImportant": false,
                "isOnline": true,
                "ip": "10.1.172.94",
                "machineGuid": 
                 "22153CD0-7E57-43CD-9661-A0624711DB08",
                "machineType": "Server",
                "machineLabels": null,
                "machineOS": "Windows 2016",
                "isolateStatus": 0
              }
            ],
            "pagination": {
              "offset": 0,
              "limit": 10,
              "total": 1
            },
            "agentQueryStatus": {
              "hasFullRbac": true,
              "hasFullAgents": true
            }
          }
        }
      ]
    },
    "TimeZone": 8
  },
  "Meta": {
    "result": 1,
    "errorCode": 0,
    "errorMessgae": "Success"
  },
  "PermissionCtrl": {
    "permission": "255",
    "elements": null
  },
  "FeatureCtrl": {
    "mode": "0"
  },
  "SystemCtrl": {
    "TmcmSoDist_Role": "none"
  }
}

The following table describes the response objects specific to this API.

Name	Type	Description
agentEntity	Object	Container for `agentEntity` objects Displays attributes of the agent
agentEntity.agentGuid	String	GUID of the agent
agentEntity.serverGuid	String	GUID of the server which manages the agent
agentEntity.machineName	String	Host name of the endpoint
agentEntity.isImportant	Boolean	Specifies if the agent is tagged as important
agentEntity.isOnline	Boolean	Specifies if the agent is online
agentEntity.ip	String	IP address of the agent
agentEntity.isolateStatus	Integer	Isolation status of the agent 0: N/A 1: Normal 2: Isolated 3: Isolate command sent -pending 4: Restore agent from isolation -pending
agentEntity.machineGuid	String	GUID of the endpoint
agentEntity.machineType	String	Type of endpoint Desktop Server
agentEntity.machineLabels	String	Labels assigned to the endpoint
agentEntity.machineOS	String	Operating system of the endpoint
agentQueryStatus.hasFullRbac	Boolean	Specifies if there are endpoints hidden due to insufficient rights of the current account
agentQueryStatus.hasFullAgents	Boolean	Specifies if there are endpoints hidden after being unregistered

For more information about standard responses and response codes for this API, see the following topics: