TOC & Recently Viewed

Recently Viewed Topics

List Agents

User Permissions: Scan Manager (40)

To retrieve information about Nessus agents installed on your assets, use the API endpoint described below.

Before You Begin

Determine the ID of the scanner associated with the agents.

HTTP Request

Note: To authenticate your request, be sure to include API keys in the HTTP header of the request. For more information, see Authorization.

Request Path Syntax


Request Path Parameters

Attribute Type Description Required?
Path Parameters
scanner_id integer The ID of the scanner to query for agents. required
Query Parameters
offset integer The starting record to retrieve. If this parameter is not supplied, the default value is 0. optional
limit integer The number of records to retrieve. If you omit this parameter, uses a default of 50 records. The minimum supported limit is 1, and the maximum supported limit is 5000. optional
sort string The sort order of the returned records. Sort can only be applied to the sortable_fields specified by the filter capabilities. There may be no more than max_sort_fields number of columns used in the sort, as specified by the filter capabilities. Sort is applied, in order, in the following format: "field1:[asc|desc],field2:[asc|desc]". For example, "sort=field1:asc,field2:desc" would first sort by field1, ascending, then sort by field2, descending. optional
f string Apply a filter in the format "field:operator:value". For example, field1:match:sometext would match any records where the value of field1 contains "sometext". You can use multiple query filters. optional
ft string Filter type. If the filter type is and, the record is only returned if all filters match. If the filter type is or, the record is returned if any of the filters match. optional
w string

Wildcard filter text. Wildcard search is a mechanism where multiple fields of a record are filtered against one given filter string. If any one of the wildcard fields' values matches against the filter string, the record matches the wildcard filter. For a record to be returned, the record must pass the wildcard filter (if there is one) AND the set of standard filters.

For example, if you submit the filter, w=wild&f=field1:match:one&f=field2:match:two&ft=or, the record would match if the value of any supported wildcard fields contained the text wild, AND either field1's value contained one or field2's value contained two.

wf string A comma-delimited subset of wildcard fields to search when applying the wildcard filter, for example field1,field2. If you provide a wparameter, but do not provide a wf parameter, all wildcard fields' values are searched against the wildcard filter text. optional

Request Path Example


HTTP Response

Response Codes

Status Description
200 Returns the agent list. For more information, see "Response Body Syntax."
403 Returned if the user does not have permission to view the list.

Returned if you attempt to send too many requests in a specific period of time. For more information, see Rate Limiting.

Response Body Syntax

{ "agents": [ { "id": {integer}, "uuid": {string}, "name": {string}, "platform": {string}, "distro": {string}, "ip": {string}, "last_scanned": {integer}, "plugin_feed_id": {string}, "core_build": {string}, "core_version": {string}, "linked_on": {integer}, "last_connect": {integer}, "status": {string}, "groups": [ { "name": {string}, "id": {integer} } ] } ], "pagination": { "total": {integer}, "offset": {integer}, "limit": {integer}, "sort": [ { "name": {string}, "order": {string} } ] } }

Response Body Attributes


Object Attribute

Type Description
id integer The unique ID of the agent.
uuid string

The UUID of the agent.

Note: This value corresponds to the ID of the asset where the agent is installed. You can use this attribute to match agent data to asset data.

name string The name of the agent.
platform string The platform of the agent.
distro string The agent software distribution.
ip string The IP address of the agent.
last_scanned integer The last scanned date for the agent (in the Unix timestamp format).
plugin_feed_id string The currently loaded plugin set of the agent (null if the agent has no plugin set loaded).
core_build string Build number for the agent.
core_version string Build version for the agent.
linked_on integer The time the agent was linked (in the Unix timestamp format).
last_connect integer The last time the agent communicated with the server (in the Unix timestamp format).
status string

A status value indicating whether the agent has connected to the manager recently.

Possible values include:

  • on—The agent has connected to the manager recently and is, therefore, likely ready to scan.
  • off—The agent has not connected to the manager recently and should be considered offline.
  • init—The agent is online, but is still processing plugin updates and is not ready to scan.
groups name string The name of the agent group to which the agent belongs.
id integer The ID of the agent group to which the agent belongs.
total integer The total number of records which match any applied filters. This number may be approximate.
limit integer The number of records returned with this response.
offset integer The index of the first record retrieved.
sort name string The name of the field by which sorts the records in the response. Sort fields are listed in order of application.
order string

The direction by which sorted the records. Possible values include:

  • asc—Sorted in ascending order (for example, a-z).
  • desc—Sorted in descending order (for example, z-a).

Response Body Example

{ "agents": [ { "id": 156, "uuid": "07e496f5-d2dc-4232-9733-12e5f7d05ae3", "name": "usersmacbook.local", "platform": "DARWIN", "distro": "macosx", "ip": "", "last_scanned": 1539206978, "plugin_feed_id": "201810122051", "core_build": "17", "core_version": "7.1.1", "linked_on": 1456774734, "last_connect": 1539480598, "status": "off", "groups": [ { "name": "Headquarters Agents", "id": 8 }, { "name": "Macbook Users", "id": 3315 } ] } ], "pagination": { "total": 11, "limit": 50, "offset": 0, "sort": [ { "name": "name", "order": "asc" } ] } }

Reference Guide


Copyright © 2019 Tenable, Inc. All rights reserved. Tenable,, Tenable Network Security, Nessus, SecurityCenter, SecurityCenter Continuous View and Log Correlation Engine are registered trademarks of Tenable, Inc.., Lumin, Assure, and the Cyber Exposure Company are trademarks of Tenable, Inc. All other products or services are trademarks of their respective owners.