ListNodesCommand

Suggest an Edit

Takes in filters and returns a list of managed nodes matching the filter criteria.

Example Syntax

Use a bare-bones client and the command you need to make an API call.

import { SSMClient, ListNodesCommand } from "@aws-sdk/client-ssm"; // ES Modules import
// const { SSMClient, ListNodesCommand } = require("@aws-sdk/client-ssm"); // CommonJS import
const client = new SSMClient(config);
const input = { // ListNodesRequest
  SyncName: "STRING_VALUE",
  Filters: [ // NodeFilterList
    { // NodeFilter
      Key: "AgentType" || "AgentVersion" || "ComputerName" || "InstanceId" || "InstanceStatus" || "IpAddress" || "ManagedStatus" || "PlatformName" || "PlatformType" || "PlatformVersion" || "ResourceType" || "OrganizationalUnitId" || "OrganizationalUnitPath" || "Region" || "AccountId", // required
      Values: [ // NodeFilterValueList // required
        "STRING_VALUE",
      ],
      Type: "Equal" || "NotEqual" || "BeginWith",
    },
  ],
  NextToken: "STRING_VALUE",
  MaxResults: Number("int"),
};
const command = new ListNodesCommand(input);
const response = await client.send(command);
// { // ListNodesResult
//   Nodes: [ // NodeList
//     { // Node
//       CaptureTime: new Date("TIMESTAMP"),
//       Id: "STRING_VALUE",
//       Owner: { // NodeOwnerInfo
//         AccountId: "STRING_VALUE",
//         OrganizationalUnitId: "STRING_VALUE",
//         OrganizationalUnitPath: "STRING_VALUE",
//       },
//       Region: "STRING_VALUE",
//       NodeType: { // NodeType Union: only one key present
//         Instance: { // InstanceInfo
//           AgentType: "STRING_VALUE",
//           AgentVersion: "STRING_VALUE",
//           ComputerName: "STRING_VALUE",
//           InstanceStatus: "STRING_VALUE",
//           IpAddress: "STRING_VALUE",
//           ManagedStatus: "All" || "Managed" || "Unmanaged",
//           PlatformType: "Windows" || "Linux" || "MacOS",
//           PlatformName: "STRING_VALUE",
//           PlatformVersion: "STRING_VALUE",
//           ResourceType: "ManagedInstance" || "EC2Instance",
//         },
//       },
//     },
//   ],
//   NextToken: "STRING_VALUE",
// };

ListNodesCommand Input

See ListNodesCommandInput for more details

Parameter
Type
Description
Filters
NodeFilter[] | undefined

One or more filters. Use a filter to return a more specific list of managed nodes.

MaxResults
number | undefined

The maximum number of items to return for this call. The call also returns a token that you can specify in a subsequent call to get the next set of results.

NextToken
string | undefined

The token for the next set of items to return. (You received this token from a previous call.)

SyncName
string | undefined

The name of the Amazon Web Services managed resource data sync to retrieve information about.

For cross-account/cross-Region configurations, this parameter is required, and the name of the supported resource data sync is AWS-QuickSetup-ManagedNode.

For single account/single-Region configurations, the parameter is not required.

ListNodesCommand Output

See ListNodesCommandOutput for details

Parameter
Type
Description
$metadata
Required
ResponseMetadata
Metadata pertaining to this request.
NextToken
string | undefined

The token to use when requesting the next set of items. If there are no additional items to return, the string is empty.

Nodes
Node[] | undefined

A list of managed nodes that match the specified filter criteria.

Throws

Name
Fault
Details
InternalServerError
server

An error occurred on the server side.

InvalidFilter
client

The filter name isn't valid. Verify that you entered the correct name and try again.

InvalidNextToken
client

The specified token isn't valid.

ResourceDataSyncNotFoundException
client

The specified sync name wasn't found.

UnsupportedOperationException
client

This operation is not supported for the current account. You must first enable the Systems Manager integrated experience in your account.

SSMServiceException
Base exception class for all service exceptions from SSM service.