Runs a command remotely on a container within a task.

If you use a condition key in your IAM policy to refine the conditions for the policy statement, for example limit the actions to a specific cluster, you receive an AccessDeniedException when there is a mismatch between the condition key value and the corresponding parameter value.

For information about required permissions and considerations, see Using Amazon ECS Exec for debugging in the Amazon ECS Developer Guide .

See also: AWS API Documentation

Request Syntax

response = client.execute_command(
  • cluster (string) -- The Amazon Resource Name (ARN) or short name of the cluster the task is running in. If you do not specify a cluster, the default cluster is assumed.
  • container (string) -- The name of the container to execute the command on. A container name only needs to be specified for tasks containing multiple containers.
  • command (string) --


    The command to run on the container.

  • interactive (boolean) --


    Use this flag to run your command in interactive mode.

  • task (string) --


    The Amazon Resource Name (ARN) or ID of the task the container is part of.

Return type



Response Syntax

    'clusterArn': 'string',
    'containerArn': 'string',
    'containerName': 'string',
    'interactive': True|False,
    'session': {
        'sessionId': 'string',
        'streamUrl': 'string',
        'tokenValue': 'string'
    'taskArn': 'string'

Response Structure

  • (dict) --

    • clusterArn (string) --

      The Amazon Resource Name (ARN) of the cluster.

    • containerArn (string) --

      The Amazon Resource Name (ARN) of the container.

    • containerName (string) --

      The name of the container.

    • interactive (boolean) --

      Determines whether the execute command session is running in interactive mode. Amazon ECS only supports initiating interactive sessions, so you must specify true for this value.

    • session (dict) --

      The details of the SSM session that was created for this instance of execute-command.

      • sessionId (string) --

        The ID of the execute command session.

      • streamUrl (string) --

        A URL to the managed agent on the container that the SSM Session Manager client uses to send commands and receive output from the container.

      • tokenValue (string) --

        An encrypted token value containing session and caller information. It's used to authenticate the connection to the container.

    • taskArn (string) --

      The Amazon Resource Name (ARN) of the task.


  • ECS.Client.exceptions.ServerException
  • ECS.Client.exceptions.ClientException
  • ECS.Client.exceptions.InvalidParameterException
  • ECS.Client.exceptions.AccessDeniedException
  • ECS.Client.exceptions.ClusterNotFoundException
  • ECS.Client.exceptions.TargetNotConnectedException