SFN / Client / describe_execution

describe_execution

SFN.Client.describe_execution(**kwargs)

Provides information about a state machine execution, such as the state machine associated with the execution, the execution input and output, and relevant execution metadata. Use this API action to return the Map Run Amazon Resource Name (ARN) if the execution was dispatched by a Map Run.

If you specify a version or alias ARN when you call the StartExecution API action, DescribeExecution returns that ARN.

Note

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

Executions of an EXPRESS state machinearen’t supported by DescribeExecution unless a Map Run dispatched them.

See also: AWS API Documentation

Request Syntax

response = client.describe_execution(
    executionArn='string'
)

Parameters:

executionArn (string) –

[REQUIRED]

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

Return type:

dict

Returns:

Response Syntax

{
    'executionArn': 'string',
    'stateMachineArn': 'string',
    'name': 'string',
    'status': 'RUNNING'|'SUCCEEDED'|'FAILED'|'TIMED_OUT'|'ABORTED',
    'startDate': datetime(2015, 1, 1),
    'stopDate': datetime(2015, 1, 1),
    'input': 'string',
    'inputDetails': {
        'included': True|False
    },
    'output': 'string',
    'outputDetails': {
        'included': True|False
    },
    'traceHeader': 'string',
    'mapRunArn': 'string',
    'error': 'string',
    'cause': 'string',
    'stateMachineVersionArn': 'string',
    'stateMachineAliasArn': 'string'
}

Response Structure

• (dict) –

  • executionArn (string) –

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

  • stateMachineArn (string) –

    The Amazon Resource Name (ARN) of the executed stated machine.

  • name (string) –

    The name of the execution.

    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 execution.

  • startDate (datetime) –

    The date the execution is started.

  • stopDate (datetime) –

    If the execution ended, the date the execution stopped.

  • input (string) –

    The string that contains the JSON input data of the execution. Length constraints apply to the payload size, and are expressed as bytes in UTF-8 encoding.

  • inputDetails (dict) –

    Provides details about execution input or output.

    • included (boolean) –

      Indicates whether input or output was included in the response. Always true for API calls.

  • output (string) –

    The JSON output data of the execution. Length constraints apply to the payload size, and are expressed as bytes in UTF-8 encoding.

    Note

    This field is set only if the execution succeeds. If the execution fails, this field is null.

  • outputDetails (dict) –

    Provides details about execution input or output.

    • included (boolean) –

      Indicates whether input or output was included in the response. Always true for API calls.

  • traceHeader (string) –

    The X-Ray trace header that was passed to the execution.

  • mapRunArn (string) –

    The Amazon Resource Name (ARN) that identifies a Map Run, which dispatched this execution.

  • error (string) –

    The error string if the state machine execution failed.

  • cause (string) –

    The cause string if the state machine execution failed.

  • stateMachineVersionArn (string) –

    The Amazon Resource Name (ARN) of the state machine version associated with the execution. The version ARN is a combination of state machine ARN and the version number separated by a colon (:). For example, stateMachineARN:1.

    If you start an execution from a StartExecution request without specifying a state machine version or alias ARN, Step Functions returns a null value.

  • stateMachineAliasArn (string) –

    The Amazon Resource Name (ARN) of the state machine alias associated with the execution. The alias ARN is a combination of state machine ARN and the alias name separated by a colon (:). For example, stateMachineARN:PROD.

    If you start an execution from a StartExecution request with a state machine version ARN, this field will be null.

Exceptions

• SFN.Client.exceptions.ExecutionDoesNotExist

• SFN.Client.exceptions.InvalidArn