/

The Amazon SSM multi-region endpoint

http://ssm.{region}.amazonaws.com

POST

Describes one or more of your managed nodes, including information about the operating system platform, the version of SSM Agent installed on the managed node, node status, and so on.

If you specify one or more managed node IDs, it returns information for those managed nodes. If you don't specify node IDs, it returns information for all your managed nodes. If you specify a node ID that isn't valid or a node that you don't own, you receive an error.

Request Example

Shell

JavaScript

Java

Swift

curl --location -g --request POST 'http://ssm.{region}.amazonaws.com/' \
--header 'X-Amz-Target;' \
--header 'Content-Type: application/json' \
--data-raw '{
    "InstanceInformationFilterList": [],
    "Filters": [],
    "MaxResults": 0,
    "NextToken": "string"
}'

Response Example

200 - Example 1

{
    "InstanceInformationList": [],
    "NextToken": "string"
}

Request

Query Params

MaxResults

string

optional

Pagination limit

NextToken

string

optional

Pagination token

Header Params

X-Amz-Target

string

required

Body Params application/json

InstanceInformationFilterList

array[object (InstanceInformationFilter) {2}]

optional

This is a legacy method. We recommend that you don't use this method. Instead, use the Filters data type. Filters enables you to return node information by filtering based on tags applied to managed nodes.

>= 0 items

key

enum<string>

required

The name of the filter.

Allowed values:

InstanceIdsAgentVersionPingStatusPlatformTypesActivationIdsIamRoleResourceTypeAssociationStatus

valueSet

array[string]

required

The filter values.

>= 1 items<= 100 items

Filters

array[object (InstanceInformationStringFilter) {2}]

optional

One or more filters. Use a filter to return a more specific list of managed nodes. You can filter based on tags applied to your managed nodes. Use this Filters data type instead of InstanceInformationFilterList, which is deprecated.

>= 0 items

Key

string

required

The filter key name to describe your managed nodes.

Valid filter key values: ActivationIds | AgentVersion | AssociationStatus | IamRole | InstanceIds | PingStatus | PlatformTypes | ResourceType | SourceIds | SourceTypes | "tag-key" | "tag:{keyname}

Valid values for the AssociationStatus filter key: Success | Pending | Failed
Valid values for the PingStatus filter key: Online | ConnectionLost | Inactive (deprecated)
Valid values for the PlatformType filter key: Windows | Linux | MacOS
Valid values for the ResourceType filter key: EC2Instance | ManagedInstance
Valid values for the SourceType filter key: AWS::EC2::Instance | AWS::SSM::ManagedInstance | AWS::IoT::Thing
Valid tag examples: Key=tag-key,Values=Purpose | Key=tag:Purpose,Values=Test.

>= 1 characters

Values

array[string]

required

The filter values.

>= 1 items<= 100 items

MaxResults

integer

optional

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.

>= 5<= 50

NextToken

string

optional

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

Examples

Responses

🟢200Success

application/json

Body

InstanceInformationList

array[object (InstanceInformation) {21}]

optional

The managed node information list.

InstanceId

string

optional

The managed node ID.

Match pattern:

(^i-(\w{8}|\w{17})$)|(^mi-\w{17}$)

PingStatus

enum<string>

optional

Connection status of SSM Agent.

Allowed values:

OnlineConnectionLostInactive

LastPingDateTime

string <date-time>

optional

The date and time when the agent last pinged the Systems Manager service.

AgentVersion

string

optional

The version of SSM Agent running on your Linux managed node.

Match pattern:

^[0-9]{1,6}(\.[0-9]{1,6}){2,3}$

IsLatestVersion

boolean

optional

Indicates whether the latest version of SSM Agent is running on your Linux managed node. This field doesn't indicate whether or not the latest version is installed on Windows managed nodes, because some older versions of Windows Server use the EC2Config service to process Systems Manager requests.

PlatformType

enum<string>

optional

The operating system platform type.

Allowed values:

WindowsLinuxMacOS

PlatformName

string

optional

The name of the operating system platform running on your managed node.

PlatformVersion

string

optional

The version of the OS platform running on your managed node.

ActivationId

string

optional

The activation ID created by Amazon Web Services Systems Manager when the server or virtual machine (VM) was registered.

Match pattern:

^[0-9a-f]{8}-[0-9a-f]{4}-[0-9a-f]{4}-[0-9a-f]{4}-[0-9a-f]{12}$

IamRole

string

optional

The Identity and Access Management (IAM) role assigned to the on-premises Systems Manager managed node. This call doesn't return the IAM role for Amazon Elastic Compute Cloud (Amazon EC2) instances. To retrieve the IAM role for an EC2 instance, use the Amazon EC2 DescribeInstances operation. For information, see DescribeInstances in the Amazon EC2 API Reference or describe-instances in the Amazon Web Services CLI Command Reference.

<= 64 characters

RegistrationDate

string <date-time>

optional

The date the server or VM was registered with Amazon Web Services as a managed node.

ResourceType

enum<string>

optional

The type of instance. Instances are either EC2 instances or managed instances.

Allowed values:

ManagedInstanceDocumentEC2Instance

Name

string

optional

The name assigned to an on-premises server, edge device, or virtual machine (VM) when it is activated as a Systems Manager managed node. The name is specified as the DefaultInstanceName property using the CreateActivation command. It is applied to the managed node by specifying the Activation Code and Activation ID when you install SSM Agent on the node, as explained in Install SSM Agent for a hybrid environment (Linux) and Install SSM Agent for a hybrid environment (Windows). To retrieve the Name tag of an EC2 instance, use the Amazon EC2 DescribeInstances operation. For information, see DescribeInstances in the Amazon EC2 API Reference or describe-instances in the Amazon Web Services CLI Command Reference.

IPAddress

string

optional

The IP address of the managed node.

>= 1 characters<= 46 characters

ComputerName

string

optional

The fully qualified host name of the managed node.

>= 1 characters<= 255 characters

AssociationStatus

string

optional

The status of the association.

LastAssociationExecutionDate

string <date-time>

optional

The date the association was last run.

LastSuccessfulAssociationExecutionDate

string <date-time>

optional

The last date the association was successfully run.

AssociationOverview

object

optional

Information about the association.

SourceId

string

optional

The ID of the source resource. For IoT Greengrass devices, SourceId is the Thing name.

>= 0 characters<= 128 characters

Match pattern:

^[a-zA-Z0-9:_-]*$

SourceType

enum<string>

optional

The type of the source resource. For IoT Greengrass devices, SourceType is AWS::IoT::Thing.

Allowed values:

AWS::EC2::InstanceAWS::IoT::ThingAWS::SSM::ManagedInstance

NextToken

string

optional

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

🟠480InternalServerError

🟠481InvalidInstanceId

🟠482InvalidNextToken

🟠483InvalidInstanceInformationFilterValue

🟠484InvalidFilterKey