:doc:`SFN <../../stepfunctions>` / Client / start_execution

***************
start_execution
***************



.. py:method:: SFN.Client.start_execution(**kwargs)

  

  Starts a state machine execution.

   

  A qualified state machine ARN can either refer to a *Distributed Map state* defined within a state machine, a version ARN, or an alias ARN.

   

  The following are some examples of qualified and unqualified state machine ARNs:

   

  
  * The following qualified state machine ARN refers to a *Distributed Map state* with a label ``mapStateLabel`` in a state machine named ``myStateMachine``. ``arn:partition:states:region:account-id:stateMachine:myStateMachine/mapStateLabel`` 

  .. note::

    If you provide a qualified state machine ARN that refers to a *Distributed Map state*, the request fails with ``ValidationException``.

  
   
  * The following qualified state machine ARN refers to an alias named ``PROD``. ``arn:<partition>:states:<region>:<account-id>:stateMachine:<myStateMachine:PROD>`` 

  .. note::

    If you provide a qualified state machine ARN that refers to a version ARN or an alias ARN, the request starts execution for that version or alias.

  
   
  * The following unqualified state machine ARN refers to a state machine named ``myStateMachine``. ``arn:<partition>:states:<region>:<account-id>:stateMachine:<myStateMachine>``
  

   

  If you start an execution with an unqualified state machine ARN, Step Functions uses the latest revision of the state machine for the execution.

   

  To start executions of a state machine `version <https://docs.aws.amazon.com/step-functions/latest/dg/concepts-state-machine-version.html>`__, call ``StartExecution`` and provide the version ARN or the ARN of an `alias <https://docs.aws.amazon.com/step-functions/latest/dg/concepts-state-machine-alias.html>`__ that points to the version.

   

  .. note::

    

    ``StartExecution`` is idempotent for ``STANDARD`` workflows. For a ``STANDARD`` workflow, if you call ``StartExecution`` with the same name and input as a running execution, the call succeeds and return the same response as the original request. If the execution is closed or if the input is different, it returns a ``400 ExecutionAlreadyExists`` error. You can reuse names after 90 days.

     

    ``StartExecution`` isn't idempotent for ``EXPRESS`` workflows.

    

  

  See also: `AWS API Documentation <https://docs.aws.amazon.com/goto/WebAPI/states-2016-11-23/StartExecution>`_  


  **Request Syntax**
  ::

    response = client.start_execution(
        stateMachineArn='string',
        name='string',
        input='string',
        traceHeader='string'
    )
    
  :type stateMachineArn: string
  :param stateMachineArn: **[REQUIRED]** 

    The Amazon Resource Name (ARN) of the state machine to execute.

     

    The ``stateMachineArn`` parameter accepts one of the following inputs:

     

    
    * **An unqualified state machine ARN** – Refers to a state machine ARN that isn't qualified with a version or alias ARN. The following is an example of an unqualified state machine ARN. ``arn:<partition>:states:<region>:<account-id>:stateMachine:<myStateMachine>`` Step Functions doesn't associate state machine executions that you start with an unqualified ARN with a version. This is true even if that version uses the same revision that the execution used.
     
    * **A state machine version ARN** – Refers to a version ARN, which is a combination of state machine ARN and the version number separated by a colon (:). The following is an example of the ARN for version 10. ``arn:<partition>:states:<region>:<account-id>:stateMachine:<myStateMachine>:10`` Step Functions doesn't associate executions that you start with a version ARN with any aliases that point to that version.
     
    * **A state machine alias ARN** – Refers to an alias ARN, which is a combination of state machine ARN and the alias name separated by a colon (:). The following is an example of the ARN for an alias named ``PROD``. ``arn:<partition>:states:<region>:<account-id>:stateMachine:<myStateMachine:PROD>`` Step Functions associates executions that you start with an alias ARN with that alias and the state machine version used for that execution.
    

    

  
  :type name: string
  :param name: 

    Optional name of the execution. This name must be unique for your Amazon Web Services account, Region, and state machine for 90 days. For more information, see `Limits Related to State Machine Executions <https://docs.aws.amazon.com/step-functions/latest/dg/limits.html#service-limits-state-machine-executions>`__ in the *Step Functions Developer Guide*.

     

    If you don't provide a name for the execution, Step Functions automatically generates a universally unique identifier (UUID) as the execution name.

     

    A name must *not* contain:

     

    
    * white space
     
    * brackets ``< > { } [ ]``
     
    * wildcard characters ``? *``
     
    * special characters ``" # % \ ^ | ~ ` $ & , ; : /``
     
    * control characters ( ``U+0000-001F``, ``U+007F-009F``, ``U+FFFE-FFFF``)
     
    * surrogates ( ``U+D800-DFFF``)
     
    * invalid characters ( `` U+10FFFF``)
    

     

    To enable logging with CloudWatch Logs, the name should only contain 0-9, A-Z, a-z, - and _.

    

  
  :type input: string
  :param input: 

    The string that contains the JSON input data for the execution, for example:

     

    ``"{\"first_name\" : \"Alejandro\"}"``

     

    .. note::

      

      If you don't include any JSON input data, you still must include the two braces, for example: ``"{}"``

      

     

    Length constraints apply to the payload size, and are expressed as bytes in UTF-8 encoding.

    

  
  :type traceHeader: string
  :param traceHeader: 

    Passes the X-Ray trace header. The trace header can also be passed in the request payload.

     

    .. note::

      

      For X-Ray traces, all Amazon Web Services services use the ``X-Amzn-Trace-Id`` header from the HTTP request. Using the header is the preferred mechanism to identify a trace. ``StartExecution`` and ``StartSyncExecution`` API operations can also use ``traceHeader`` from the body of the request payload. If **both** sources are provided, Step Functions will use the **header value** (preferred) over the value in the request body.

      

    

  
  
  :rtype: dict
  :returns: 
    
    **Response Syntax**

    
    ::

      {
          'executionArn': 'string',
          'startDate': datetime(2015, 1, 1)
      }
      
    **Response Structure**

    

    - *(dict) --* 
      

      - **executionArn** *(string) --* 

        The Amazon Resource Name (ARN) that identifies the execution.

        
      

      - **startDate** *(datetime) --* 

        The date the execution is started.

        
  
  **Exceptions**
  
  *   :py:class:`SFN.Client.exceptions.ExecutionLimitExceeded`

  
  *   :py:class:`SFN.Client.exceptions.ExecutionAlreadyExists`

  
  *   :py:class:`SFN.Client.exceptions.InvalidArn`

  
  *   :py:class:`SFN.Client.exceptions.InvalidExecutionInput`

  
  *   :py:class:`SFN.Client.exceptions.InvalidName`

  
  *   :py:class:`SFN.Client.exceptions.StateMachineDoesNotExist`

  
  *   :py:class:`SFN.Client.exceptions.StateMachineDeleting`

  
  *   :py:class:`SFN.Client.exceptions.ValidationException`

  
  *   :py:class:`SFN.Client.exceptions.KmsAccessDeniedException`

  
  *   :py:class:`SFN.Client.exceptions.KmsInvalidStateException`

  
  *   :py:class:`SFN.Client.exceptions.KmsThrottlingException`

  