SFN / Client / describe_state_machine



Provides information about a state machine’s definition, its IAM role Amazon Resource Name (ARN), and configuration. If the state machine ARN is a qualified state machine ARN, the response returned includes the Map state’s label.

A qualified state machine ARN refers to a Distributed Map state defined within a state machine. For example, the qualified state machine ARN arn:partition:states:region:account-id:stateMachine:stateMachineName/mapStateLabel refers to a Distributed Map state with a label mapStateLabel in the state machine named stateMachineName.


This operation is eventually consistent. The results are best effort and may not reflect very recent updates and changes.

See also: AWS API Documentation

Request Syntax

response = client.describe_state_machine(

stateMachineArn (string) –


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

Return type:



Response Syntax

    'stateMachineArn': 'string',
    'name': 'string',
    'status': 'ACTIVE'|'DELETING',
    'definition': 'string',
    'roleArn': 'string',
    'type': 'STANDARD'|'EXPRESS',
    'creationDate': datetime(2015, 1, 1),
    'loggingConfiguration': {
        'level': 'ALL'|'ERROR'|'FATAL'|'OFF',
        'includeExecutionData': True|False,
        'destinations': [
                'cloudWatchLogsLogGroup': {
                    'logGroupArn': 'string'
    'tracingConfiguration': {
        'enabled': True|False
    'label': 'string'

Response Structure

  • (dict) –

    • stateMachineArn (string) –

      The Amazon Resource Name (ARN) that identifies the state machine.

    • name (string) –

      The name of the state machine.

      A name must not contain:

      • white space

      • brackets < > { } [ ]

      • wildcard characters ? *

      • special characters " # % \ ^ | ~ ` $ & , ; : /

      • control characters ( U+0000-001F, U+007F-009F)

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

    • status (string) –

      The current status of the state machine.

    • definition (string) –

      The Amazon States Language definition of the state machine. See Amazon States Language.

    • roleArn (string) –

      The Amazon Resource Name (ARN) of the IAM role used when creating this state machine. (The IAM role maintains security by granting Step Functions access to Amazon Web Services resources.)

    • type (string) –

      The type of the state machine ( STANDARD or EXPRESS).

    • creationDate (datetime) –

      The date the state machine is created.

    • loggingConfiguration (dict) –

      The LoggingConfiguration data type is used to set CloudWatch Logs options.

      • level (string) –

        Defines which category of execution history events are logged.

      • includeExecutionData (boolean) –

        Determines whether execution data is included in your log. When set to false, data is excluded.

      • destinations (list) –

        An array of objects that describes where your execution history events will be logged. Limited to size 1. Required, if your log level is not set to OFF.

        • (dict) –

          • cloudWatchLogsLogGroup (dict) –

            An object describing a CloudWatch log group. For more information, see AWS::Logs::LogGroup in the CloudFormation User Guide.

            • logGroupArn (string) –

              The ARN of the the CloudWatch log group to which you want your logs emitted to. The ARN must end with :*

    • tracingConfiguration (dict) –

      Selects whether X-Ray tracing is enabled.

      • enabled (boolean) –

        When set to true, X-Ray tracing is enabled.

    • label (string) –

      A user-defined or an auto-generated string that identifies a Map state. This parameter is present only if the stateMachineArn specified in input is a qualified state machine ARN.


  • SFN.Client.exceptions.InvalidArn

  • SFN.Client.exceptions.StateMachineDoesNotExist