CreateAssociationBatch - AWS Systems Manager
AWS services or capabilities described in AWS documentation might vary by Region. To see the differences applicable to the China Regions, see Getting Started with AWS services in China.


Associates the specified Systems Manager document with the specified instances or targets.

When you associate a document with one or more instances using instance IDs or tags, SSM Agent running on the instance processes the document and configures the instance as specified.

If you associate a document with an instance that already has an associated document, the system returns the AssociationAlreadyExists exception.

Request Syntax

{ "Entries": [ { "ApplyOnlyAtCronInterval": boolean, "AssociationName": "string", "AutomationTargetParameterName": "string", "ComplianceSeverity": "string", "DocumentVersion": "string", "InstanceId": "string", "MaxConcurrency": "string", "MaxErrors": "string", "Name": "string", "OutputLocation": { "S3Location": { "OutputS3BucketName": "string", "OutputS3KeyPrefix": "string", "OutputS3Region": "string" } }, "Parameters": { "string" : [ "string" ] }, "ScheduleExpression": "string", "SyncCompliance": "string", "TargetLocations": [ { "Accounts": [ "string" ], "ExecutionRoleName": "string", "Regions": [ "string" ], "TargetLocationMaxConcurrency": "string", "TargetLocationMaxErrors": "string" } ], "Targets": [ { "Key": "string", "Values": [ "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.


One or more associations.

Type: Array of CreateAssociationBatchRequestEntry objects

Array Members: Minimum number of 1 item.

Required: Yes

Response Syntax

{ "Failed": [ { "Entry": { "ApplyOnlyAtCronInterval": boolean, "AssociationName": "string", "AutomationTargetParameterName": "string", "ComplianceSeverity": "string", "DocumentVersion": "string", "InstanceId": "string", "MaxConcurrency": "string", "MaxErrors": "string", "Name": "string", "OutputLocation": { "S3Location": { "OutputS3BucketName": "string", "OutputS3KeyPrefix": "string", "OutputS3Region": "string" } }, "Parameters": { "string" : [ "string" ] }, "ScheduleExpression": "string", "SyncCompliance": "string", "TargetLocations": [ { "Accounts": [ "string" ], "ExecutionRoleName": "string", "Regions": [ "string" ], "TargetLocationMaxConcurrency": "string", "TargetLocationMaxErrors": "string" } ], "Targets": [ { "Key": "string", "Values": [ "string" ] } ] }, "Fault": "string", "Message": "string" } ], "Successful": [ { "ApplyOnlyAtCronInterval": boolean, "AssociationId": "string", "AssociationName": "string", "AssociationVersion": "string", "AutomationTargetParameterName": "string", "ComplianceSeverity": "string", "Date": number, "DocumentVersion": "string", "InstanceId": "string", "LastExecutionDate": number, "LastSuccessfulExecutionDate": number, "LastUpdateAssociationDate": number, "MaxConcurrency": "string", "MaxErrors": "string", "Name": "string", "OutputLocation": { "S3Location": { "OutputS3BucketName": "string", "OutputS3KeyPrefix": "string", "OutputS3Region": "string" } }, "Overview": { "AssociationStatusAggregatedCount": { "string" : number }, "DetailedStatus": "string", "Status": "string" }, "Parameters": { "string" : [ "string" ] }, "ScheduleExpression": "string", "Status": { "AdditionalInfo": "string", "Date": number, "Message": "string", "Name": "string" }, "SyncCompliance": "string", "TargetLocations": [ { "Accounts": [ "string" ], "ExecutionRoleName": "string", "Regions": [ "string" ], "TargetLocationMaxConcurrency": "string", "TargetLocationMaxErrors": "string" } ], "Targets": [ { "Key": "string", "Values": [ "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.


Information about the associations that failed.

Type: Array of FailedCreateAssociation objects


Information about the associations that succeeded.

Type: Array of AssociationDescription objects


For information about the errors that are common to all actions, see Common Errors.


You can have at most 2,000 active associations.

HTTP Status Code: 400


You cannot specify an instance ID in more than one association.

HTTP Status Code: 400


An error occurred on the server side.

HTTP Status Code: 500


The specified document does not exist.

HTTP Status Code: 400


The document version is not valid or does not exist.

HTTP Status Code: 400


The following problems can cause this exception:

You do not have permission to access the instance.

SSM Agent is not running. Verify that SSM Agent is running.

SSM Agent is not registered with the SSM endpoint. Try reinstalling SSM Agent.

The instance is not in valid state. Valid states are: Running, Pending, Stopped, Stopping. Invalid states are: Shutting-down and Terminated.

HTTP Status Code: 400


The output location is not valid or does not exist.

HTTP Status Code: 400


You must specify values for all required parameters in the Systems Manager document. You can only supply values to parameters defined in the Systems Manager document.

HTTP Status Code: 400


The schedule is invalid. Verify your cron or rate expression and try again.

HTTP Status Code: 400


The target is not valid or does not exist. It might not be configured for Systems Manager or you might not have permission to perform the operation.

HTTP Status Code: 400


The document does not support the platform type of the given instance ID(s). For example, you sent an document for a Windows instance to a Linux instance.

HTTP Status Code: 400



This example illustrates one usage of CreateAssociationBatch.

Sample Request

POST / HTTP/1.1 Host: Accept-Encoding: identity X-Amz-Target: AmazonSSM.CreateAssociationBatch Content-Type: application/x-amz-json-1.1 User-Agent: aws-cli/1.17.12 Python/3.6.8 Darwin/18.7.0 botocore/1.14.12 X-Amz-Date: 20200324T142446Z Authorization: AWS4-HMAC-SHA256 Credential=AKIAIOSFODNN7EXAMPLE/20200324/us-east-2/ssm/aws4_request, SignedHeaders=content-type;host;x-amz-date;x-amz-target, Signature=39c3b3042cd2aEXAMPLE Content-Length: 151 { "Entries":[ { "InstanceId":"i-0471e04240EXAMPLE", "Name":"AWS-UpdateSSMAgent" }, { "InstanceId":"i-07782c72faEXAMPLE", "Name":"AWS-UpdateSSMAgent" } ] }

Sample Response

{ "Failed":[ ], "Successful":[ { "ApplyOnlyAtCronInterval":false, "AssociationId":"33858bec-0c55-4547-a054-eb5fcEXAMPLE", "AssociationVersion":"1", "Date":1.585059887692E9, "DocumentVersion":"$DEFAULT", "InstanceId":"i-0471e04240EXAMPLE", "LastUpdateAssociationDate":1.585059887692E9, "Name":"AWS-UpdateSSMAgent", "Overview":{ "DetailedStatus":"Creating", "Status":"Pending" }, "Status":{ "Date":1.585059887692E9, "Message":"Associated with AWS-UpdateSSMAgent", "Name":"Associated" }, "Targets":[ { "Key":"InstanceIds", "Values":[ "i-0471e04240EXAMPLE" ] } ] }, { "ApplyOnlyAtCronInterval":false, "AssociationId":"e0e0a062-3dcb-4b3e-bb2b-d01b4EXAMPLE", "AssociationVersion":"1", "Date":1.585059887726E9, "DocumentVersion":"$DEFAULT", "InstanceId":"i-07782c72faEXAMPLE", "LastUpdateAssociationDate":1.585059887726E9, "Name":"AWS-UpdateSSMAgent", "Overview":{ "DetailedStatus":"Creating", "Status":"Pending" }, "Status":{ "Date":1.585059887726E9, "Message":"Associated with AWS-UpdateSSMAgent", "Name":"Associated" }, "Targets":[ { "Key":"InstanceIds", "Values":[ "i-07782c72faEXAMPLE" ] } ] } ] }

See Also

For more information about using this API in one of the language-specific AWS SDKs, see the following: