Menu
AWS Systems Manager
API Reference (API Version 2014-11-06)

GetCommandInvocation

Returns detailed information about command execution for an invocation or plugin.

Request Syntax

{
   "CommandId": "string",
   "InstanceId": "string",
   "PluginName": "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.

CommandId

(Required) The parent command ID of the invocation plugin.

Type: String

Length Constraints: Fixed length of 36.

Required: Yes

InstanceId

(Required) The ID of the managed instance targeted by the command. A managed instance can be an Amazon EC2 instance or an instance in your hybrid environment that is configured for Systems Manager.

Type: String

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

Required: Yes

PluginName

(Optional) The name of the plugin for which you want detailed results. If the document contains only one plugin, the name can be omitted and the details will be returned.

Type: String

Length Constraints: Minimum length of 4.

Required: No

Response Syntax

{
   "CommandId": "string",
   "Comment": "string",
   "DocumentName": "string",
   "ExecutionElapsedTime": "string",
   "ExecutionEndDateTime": "string",
   "ExecutionStartDateTime": "string",
   "InstanceId": "string",
   "PluginName": "string",
   "ResponseCode": number,
   "StandardErrorContent": "string",
   "StandardErrorUrl": "string",
   "StandardOutputContent": "string",
   "StandardOutputUrl": "string",
   "Status": "string",
   "StatusDetails": "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.

CommandId

The parent command ID of the invocation plugin.

Type: String

Length Constraints: Fixed length of 36.

Comment

The comment text for the command.

Type: String

Length Constraints: Maximum length of 100.

DocumentName

The name of the document that was executed. For example, AWS-RunShellScript.

Type: String

Pattern: ^[a-zA-Z0-9_\-.]{3,128}$

ExecutionElapsedTime

Duration since ExecutionStartDateTime.

Type: String

Pattern: ^([\-]?\d{4}(?!\d{2}\b))((-?)((0[1-9]|1[0-2])(\3([12]\d|0[1-9]|3[01]))?|W([0-4]\d|5[0-2])(-?[1-7])?|(00[1-9]|0[1-9]\d|[12]\d{2}|3([0-5]\d|6[1-6])))([T\s]((([01]\d|2[0-3])((:?)[0-5]\d)?|24\:?00)([\.,]\d(?!:))?)?(\17[0-5]\d([\.,]\d)?)?([zZ]|([\-])([01]\d|2[0-3]):?([0-5]\d)?)?)?)?$

ExecutionEndDateTime

The date and time the plugin was finished executing. Date and time are written in ISO 8601 format. For example, June 7, 2017 is represented as 2017-06-7. The following sample AWS CLI command uses the InvokedAfter filter.

aws ssm list-commands --filters key=InvokedAfter,value=2017-06-07T00:00:00Z

If the plugin has not started to execute, the string is empty.

Type: String

Pattern: ^([\-]?\d{4}(?!\d{2}\b))((-?)((0[1-9]|1[0-2])(\3([12]\d|0[1-9]|3[01]))?|W([0-4]\d|5[0-2])(-?[1-7])?|(00[1-9]|0[1-9]\d|[12]\d{2}|3([0-5]\d|6[1-6])))([T\s]((([01]\d|2[0-3])((:?)[0-5]\d)?|24\:?00)([\.,]\d(?!:))?)?(\17[0-5]\d([\.,]\d)?)?([zZ]|([\-])([01]\d|2[0-3]):?([0-5]\d)?)?)?)?$

ExecutionStartDateTime

The date and time the plugin started executing. Date and time are written in ISO 8601 format. For example, June 7, 2017 is represented as 2017-06-7. The following sample AWS CLI command uses the InvokedBefore filter.

aws ssm list-commands --filters key=InvokedBefore,value=2017-06-07T00:00:00Z

If the plugin has not started to execute, the string is empty.

Type: String

Pattern: ^([\-]?\d{4}(?!\d{2}\b))((-?)((0[1-9]|1[0-2])(\3([12]\d|0[1-9]|3[01]))?|W([0-4]\d|5[0-2])(-?[1-7])?|(00[1-9]|0[1-9]\d|[12]\d{2}|3([0-5]\d|6[1-6])))([T\s]((([01]\d|2[0-3])((:?)[0-5]\d)?|24\:?00)([\.,]\d(?!:))?)?(\17[0-5]\d([\.,]\d)?)?([zZ]|([\-])([01]\d|2[0-3]):?([0-5]\d)?)?)?)?$

InstanceId

The ID of the managed instance targeted by the command. A managed instance can be an Amazon EC2 instance or an instance in your hybrid environment that is configured for Systems Manager.

Type: String

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

PluginName

The name of the plugin for which you want detailed results. For example, aws:RunShellScript is a plugin.

Type: String

Length Constraints: Minimum length of 4.

ResponseCode

The error level response code for the plugin script. If the response code is -1, then the command has not started executing on the instance, or it was not received by the instance.

Type: Integer

StandardErrorContent

The first 8,000 characters written by the plugin to stderr. If the command has not finished executing, then this string is empty.

Type: String

Length Constraints: Maximum length of 8000.

StandardErrorUrl

The URL for the complete text written by the plugin to stderr. If the command has not finished executing, then this string is empty.

Type: String

StandardOutputContent

The first 24,000 characters written by the plugin to stdout. If the command has not finished executing, if ExecutionStatus is neither Succeeded nor Failed, then this string is empty.

Type: String

Length Constraints: Maximum length of 24000.

StandardOutputUrl

The URL for the complete text written by the plugin to stdout in Amazon S3. If an Amazon S3 bucket was not specified, then this string is empty.

Type: String

Status

The status of the parent command for this invocation. This status can be different than StatusDetails.

Type: String

Valid Values: Pending | InProgress | Delayed | Success | Cancelled | TimedOut | Failed | Cancelling

StatusDetails

A detailed status of the command execution for an invocation. StatusDetails includes more information than Status because it includes states resulting from error and concurrency control parameters. StatusDetails can show different results than Status. For more information about these statuses, see Run Command Status. StatusDetails can be one of the following values:

  • Pending: The command has not been sent to the instance.

  • In Progress: The command has been sent to the instance but has not reached a terminal state.

  • Delayed: The system attempted to send the command to the target, but the target was not available. The instance might not be available because of network issues, the instance was stopped, etc. The system will try to deliver the command again.

  • Success: The command or plugin was executed successfully. This is a terminal state.

  • Delivery Timed Out: The command was not delivered to the instance before the delivery timeout expired. Delivery timeouts do not count against the parent command's MaxErrors limit, but they do contribute to whether the parent command status is Success or Incomplete. This is a terminal state.

  • Execution Timed Out: The command started to execute on the instance, but the execution was not complete before the timeout expired. Execution timeouts count against the MaxErrors limit of the parent command. This is a terminal state.

  • Failed: The command wasn't executed successfully on the instance. For a plugin, this indicates that the result code was not zero. For a command invocation, this indicates that the result code for one or more plugins was not zero. Invocation failures count against the MaxErrors limit of the parent command. This is a terminal state.

  • Canceled: The command was terminated before it was completed. This is a terminal state.

  • Undeliverable: The command can't be delivered to the instance. The instance might not exist or might not be responding. Undeliverable invocations don't count against the parent command's MaxErrors limit and don't contribute to whether the parent command status is Success or Incomplete. This is a terminal state.

  • Terminated: The parent command exceeded its MaxErrors limit and subsequent command invocations were canceled by the system. This is a terminal state.

Type: String

Length Constraints: Minimum length of 0. Maximum length of 100.

Errors

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

InternalServerError

An error occurred on the server side.

HTTP Status Code: 400

InvalidCommandId

HTTP Status Code: 400

InvalidInstanceId

The following problems can cause this exception:

You do not have permission to access the instance.

The SSM Agent is not running. On managed instances and Linux instances, verify that the SSM Agent is running. On EC2 Windows instances, verify that the EC2Config service is running.

The SSM Agent or EC2Config service is not registered to the SSM endpoint. Try reinstalling the SSM Agent or EC2Config service.

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

InvalidPluginName

The plugin name is not valid.

HTTP Status Code: 400

InvocationDoesNotExist

The command ID and instance ID you specified did not match any invocations. Verify the command ID adn the instance ID and try again.

HTTP Status Code: 400

See Also

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