SDK for PHP 3.x

Client: Aws\Sfn\SfnClient
Service ID: states
Version: 2016-11-23

This page describes the parameters and results for the operations of the AWS Step Functions (2016-11-23), and shows how to use the Aws\Sfn\SfnClient object to call the described operations. This documentation is specific to the 2016-11-23 API version of the service.

Operation Summary

Each of the following operations can be created from a client using $client->getCommand('CommandName'), where "CommandName" is the name of one of the following operations. Note: a command is a value that encapsulates an operation and the parameters used to create an HTTP request.

You can also create and send a command immediately using the magic methods available on a client object: $client->commandName(/* parameters */). You can send the command asynchronously (returning a promise) by appending the word "Async" to the operation name: $client->commandNameAsync(/* parameters */).

CreateActivity ( array $params = [] )
Creates an activity.
CreateStateMachine ( array $params = [] )
Creates a state machine.
CreateStateMachineAlias ( array $params = [] )
Creates an alias for a state machine that points to one or two versions of the same state machine.
DeleteActivity ( array $params = [] )
Deletes an activity.
DeleteStateMachine ( array $params = [] )
Deletes a state machine.
DeleteStateMachineAlias ( array $params = [] )
Deletes a state machine alias.
DeleteStateMachineVersion ( array $params = [] )
Deletes a state machine version.
DescribeActivity ( array $params = [] )
Describes an activity.
DescribeExecution ( array $params = [] )
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.
DescribeMapRun ( array $params = [] )
Provides information about a Map Run's configuration, progress, and results.
DescribeStateMachine ( array $params = [] )
Provides information about a state machine's definition, its IAM role Amazon Resource Name (ARN), and configuration.
DescribeStateMachineAlias ( array $params = [] )
Returns details about a state machine alias.
DescribeStateMachineForExecution ( array $params = [] )
Provides information about a state machine's definition, its execution role ARN, and configuration.
GetActivityTask ( array $params = [] )
Used by workers to retrieve a task (with the specified activity ARN) which has been scheduled for execution by a running state machine.
GetExecutionHistory ( array $params = [] )
Returns the history of the specified execution as a list of events.
ListActivities ( array $params = [] )
Lists the existing activities.
ListExecutions ( array $params = [] )
Lists all executions of a state machine or a Map Run.
ListMapRuns ( array $params = [] )
Lists all Map Runs that were started by a given state machine execution.
ListStateMachineAliases ( array $params = [] )
Lists aliases for a specified state machine ARN.
ListStateMachineVersions ( array $params = [] )
Lists versions for the specified state machine Amazon Resource Name (ARN).
ListStateMachines ( array $params = [] )
Lists the existing state machines.
ListTagsForResource ( array $params = [] )
List tags for a given resource.
PublishStateMachineVersion ( array $params = [] )
Creates a version from the current revision of a state machine.
RedriveExecution ( array $params = [] )
Restarts unsuccessful executions of Standard workflows that didn't complete successfully in the last 14 days.
SendTaskFailure ( array $params = [] )
Used by activity workers, Task states using the callback pattern, and optionally Task states using the job run pattern to report that the task identified by the taskToken failed.
SendTaskHeartbeat ( array $params = [] )
Used by activity workers and Task states using the callback pattern, and optionally Task states using the job run pattern to report to Step Functions that the task represented by the specified taskToken is still making progress.
SendTaskSuccess ( array $params = [] )
Used by activity workers, Task states using the callback pattern, and optionally Task states using the job run pattern to report that the task identified by the taskToken completed successfully.
StartExecution ( array $params = [] )
Starts a state machine execution.
StartSyncExecution ( array $params = [] )
Starts a Synchronous Express state machine execution.
StopExecution ( array $params = [] )
Stops an execution.
TagResource ( array $params = [] )
Add a tag to a Step Functions resource.
TestState ( array $params = [] )
Accepts the definition of a single state and executes it.
UntagResource ( array $params = [] )
Remove a tag from a Step Functions resource
UpdateMapRun ( array $params = [] )
Updates an in-progress Map Run's configuration to include changes to the settings that control maximum concurrency and Map Run failure.
UpdateStateMachine ( array $params = [] )
Updates an existing state machine by modifying its definition, roleArn, loggingConfiguration, or EncryptionConfiguration.
UpdateStateMachineAlias ( array $params = [] )
Updates the configuration of an existing state machine alias by modifying its description or routingConfiguration.
ValidateStateMachineDefinition ( array $params = [] )
Validates the syntax of a state machine definition.

Paginators

Paginators handle automatically iterating over paginated API results. Paginators are associated with specific API operations, and they accept the parameters that the corresponding API operation accepts. You can get a paginator from a client class using getPaginator($paginatorName, $operationParameters). This client supports the following paginators:

GetExecutionHistory
ListActivities
ListExecutions
ListMapRuns
ListStateMachines

Operations

CreateActivity

$result = $client->createActivity([/* ... */]);
$promise = $client->createActivityAsync([/* ... */]);

Creates an activity. An activity is a task that you write in any programming language and host on any machine that has access to Step Functions. Activities must poll Step Functions using the GetActivityTask API action and respond using SendTask* API actions. This function lets Step Functions know the existence of your activity and returns an identifier for use in a state machine and when polling from the activity.

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

CreateActivity is an idempotent API. Subsequent requests won’t create a duplicate resource if it was already created. CreateActivity's idempotency check is based on the activity name. If a following request has different tags values, Step Functions will ignore these differences and treat it as an idempotent request of the previous. In this case, tags will not be updated, even if they are different.

Parameter Syntax

$result = $client->createActivity([
    'encryptionConfiguration' => [
        'kmsDataKeyReusePeriodSeconds' => <integer>,
        'kmsKeyId' => '<string>',
        'type' => 'AWS_OWNED_KEY|CUSTOMER_MANAGED_KMS_KEY', // REQUIRED
    ],
    'name' => '<string>', // REQUIRED
    'tags' => [
        [
            'key' => '<string>',
            'value' => '<string>',
        ],
        // ...
    ],
]);

Parameter Details

Members
encryptionConfiguration
Type: EncryptionConfiguration structure

Settings to configure server-side encryption.

name
Required: Yes
Type: string

The name of the activity to create. This name must be unique for your Amazon Web Services account and region for 90 days. For more information, see Limits Related to State Machine Executions in the Step Functions Developer Guide.

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

tags
Type: Array of Tag structures

The list of tags to add to a resource.

An array of key-value pairs. For more information, see Using Cost Allocation Tags in the Amazon Web Services Billing and Cost Management User Guide, and Controlling Access Using IAM Tags.

Tags may only contain Unicode letters, digits, white space, or these symbols: _ . : / = + - @.

Result Syntax

[
    'activityArn' => '<string>',
    'creationDate' => <DateTime>,
]

Result Details

Members
activityArn
Required: Yes
Type: string

The Amazon Resource Name (ARN) that identifies the created activity.

creationDate
Required: Yes
Type: timestamp (string|DateTime or anything parsable by strtotime)

The date the activity is created.

Errors

ActivityLimitExceeded:

The maximum number of activities has been reached. Existing activities must be deleted before a new activity can be created.

ActivityAlreadyExists:

Activity already exists. EncryptionConfiguration may not be updated.

InvalidName:

The provided name is not valid.

TooManyTags:

You've exceeded the number of tags allowed for a resource. See the Limits Topic in the Step Functions Developer Guide.

InvalidEncryptionConfiguration:

Received when encryptionConfiguration is specified but various conditions exist which make the configuration invalid. For example, if type is set to CUSTOMER_MANAGED_KMS_KEY, but kmsKeyId is null, or kmsDataKeyReusePeriodSeconds is not between 60 and 900, or the KMS key is not symmetric or inactive.

KmsAccessDeniedException:

Either your KMS key policy or API caller does not have the required permissions.

KmsThrottlingException:

Received when KMS returns ThrottlingException for a KMS call that Step Functions makes on behalf of the caller.

CreateStateMachine

$result = $client->createStateMachine([/* ... */]);
$promise = $client->createStateMachineAsync([/* ... */]);

Creates a state machine. A state machine consists of a collection of states that can do work (Task states), determine to which states to transition next (Choice states), stop an execution with an error (Fail states), and so on. State machines are specified using a JSON-based, structured language. For more information, see Amazon States Language in the Step Functions User Guide.

If you set the publish parameter of this API action to true, it publishes version 1 as the first revision of the state machine.

For additional control over security, you can encrypt your data using a customer-managed key for Step Functions state machines. You can configure a symmetric KMS key and data key reuse period when creating or updating a State Machine. The execution history and state machine definition will be encrypted with the key applied to the State Machine.

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

CreateStateMachine is an idempotent API. Subsequent requests won’t create a duplicate resource if it was already created. CreateStateMachine's idempotency check is based on the state machine name, definition, type, LoggingConfiguration, TracingConfiguration, and EncryptionConfiguration The check is also based on the publish and versionDescription parameters. If a following request has a different roleArn or tags, Step Functions will ignore these differences and treat it as an idempotent request of the previous. In this case, roleArn and tags will not be updated, even if they are different.

Parameter Syntax

$result = $client->createStateMachine([
    'definition' => '<string>', // REQUIRED
    'encryptionConfiguration' => [
        'kmsDataKeyReusePeriodSeconds' => <integer>,
        'kmsKeyId' => '<string>',
        'type' => 'AWS_OWNED_KEY|CUSTOMER_MANAGED_KMS_KEY', // REQUIRED
    ],
    'loggingConfiguration' => [
        'destinations' => [
            [
                'cloudWatchLogsLogGroup' => [
                    'logGroupArn' => '<string>',
                ],
            ],
            // ...
        ],
        'includeExecutionData' => true || false,
        'level' => 'ALL|ERROR|FATAL|OFF',
    ],
    'name' => '<string>', // REQUIRED
    'publish' => true || false,
    'roleArn' => '<string>', // REQUIRED
    'tags' => [
        [
            'key' => '<string>',
            'value' => '<string>',
        ],
        // ...
    ],
    'tracingConfiguration' => [
        'enabled' => true || false,
    ],
    'type' => 'STANDARD|EXPRESS',
    'versionDescription' => '<string>',
]);

Parameter Details

Members
definition
Required: Yes
Type: string

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

encryptionConfiguration
Type: EncryptionConfiguration structure

Settings to configure server-side encryption.

loggingConfiguration
Type: LoggingConfiguration structure

Defines what execution history events are logged and where they are logged.

By default, the level is set to OFF. For more information see Log Levels in the Step Functions User Guide.

name
Required: Yes
Type: 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 _.

publish
Type: boolean

Set to true to publish the first version of the state machine during creation. The default is false.

roleArn
Required: Yes
Type: string

The Amazon Resource Name (ARN) of the IAM role to use for this state machine.

tags
Type: Array of Tag structures

Tags to be added when creating a state machine.

An array of key-value pairs. For more information, see Using Cost Allocation Tags in the Amazon Web Services Billing and Cost Management User Guide, and Controlling Access Using IAM Tags.

Tags may only contain Unicode letters, digits, white space, or these symbols: _ . : / = + - @.

tracingConfiguration
Type: TracingConfiguration structure

Selects whether X-Ray tracing is enabled.

type
Type: string

Determines whether a Standard or Express state machine is created. The default is STANDARD. You cannot update the type of a state machine once it has been created.

versionDescription
Type: string

Sets description about the state machine version. You can only set the description if the publish parameter is set to true. Otherwise, if you set versionDescription, but publish to false, this API action throws ValidationException.

Result Syntax

[
    'creationDate' => <DateTime>,
    'stateMachineArn' => '<string>',
    'stateMachineVersionArn' => '<string>',
]

Result Details

Members
creationDate
Required: Yes
Type: timestamp (string|DateTime or anything parsable by strtotime)

The date the state machine is created.

stateMachineArn
Required: Yes
Type: string

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

stateMachineVersionArn
Type: string

The Amazon Resource Name (ARN) that identifies the created state machine version. If you do not set the publish parameter to true, this field returns null value.

Errors

InvalidArn:

The provided Amazon Resource Name (ARN) is not valid.

InvalidDefinition:

The provided Amazon States Language definition is not valid.

InvalidName:

The provided name is not valid.

InvalidLoggingConfiguration:

Configuration is not valid.

InvalidTracingConfiguration:

Your tracingConfiguration key does not match, or enabled has not been set to true or false.

StateMachineAlreadyExists:

A state machine with the same name but a different definition or role ARN already exists.

StateMachineDeleting:

The specified state machine is being deleted.

StateMachineLimitExceeded:

The maximum number of state machines has been reached. Existing state machines must be deleted before a new state machine can be created.

StateMachineTypeNotSupported:

State machine type is not supported.

TooManyTags:

You've exceeded the number of tags allowed for a resource. See the Limits Topic in the Step Functions Developer Guide.

ValidationException:

The input does not satisfy the constraints specified by an Amazon Web Services service.

ConflictException:

Updating or deleting a resource can cause an inconsistent state. This error occurs when there're concurrent requests for DeleteStateMachineVersion, PublishStateMachineVersion, or UpdateStateMachine with the publish parameter set to true.

HTTP Status Code: 409

InvalidEncryptionConfiguration:

Received when encryptionConfiguration is specified but various conditions exist which make the configuration invalid. For example, if type is set to CUSTOMER_MANAGED_KMS_KEY, but kmsKeyId is null, or kmsDataKeyReusePeriodSeconds is not between 60 and 900, or the KMS key is not symmetric or inactive.

KmsAccessDeniedException:

Either your KMS key policy or API caller does not have the required permissions.

KmsThrottlingException:

Received when KMS returns ThrottlingException for a KMS call that Step Functions makes on behalf of the caller.

CreateStateMachineAlias

$result = $client->createStateMachineAlias([/* ... */]);
$promise = $client->createStateMachineAliasAsync([/* ... */]);

Creates an alias for a state machine that points to one or two versions of the same state machine. You can set your application to call StartExecution with an alias and update the version the alias uses without changing the client's code.

You can also map an alias to split StartExecution requests between two versions of a state machine. To do this, add a second RoutingConfig object in the routingConfiguration parameter. You must also specify the percentage of execution run requests each version should receive in both RoutingConfig objects. Step Functions randomly chooses which version runs a given execution based on the percentage you specify.

To create an alias that points to a single version, specify a single RoutingConfig object with a weight set to 100.

You can create up to 100 aliases for each state machine. You must delete unused aliases using the DeleteStateMachineAlias API action.

CreateStateMachineAlias is an idempotent API. Step Functions bases the idempotency check on the stateMachineArn, description, name, and routingConfiguration parameters. Requests that contain the same values for these parameters return a successful idempotent response without creating a duplicate resource.

Related operations:

Parameter Syntax

$result = $client->createStateMachineAlias([
    'description' => '<string>',
    'name' => '<string>', // REQUIRED
    'routingConfiguration' => [ // REQUIRED
        [
            'stateMachineVersionArn' => '<string>', // REQUIRED
            'weight' => <integer>, // REQUIRED
        ],
        // ...
    ],
]);

Parameter Details

Members
description
Type: string

A description for the state machine alias.

name
Required: Yes
Type: string

The name of the state machine alias.

To avoid conflict with version ARNs, don't use an integer in the name of the alias.

routingConfiguration
Required: Yes
Type: Array of RoutingConfigurationListItem structures

The routing configuration of a state machine alias. The routing configuration shifts execution traffic between two state machine versions. routingConfiguration contains an array of RoutingConfig objects that specify up to two state machine versions. Step Functions then randomly choses which version to run an execution with based on the weight assigned to each RoutingConfig.

Result Syntax

[
    'creationDate' => <DateTime>,
    'stateMachineAliasArn' => '<string>',
]

Result Details

Members
creationDate
Required: Yes
Type: timestamp (string|DateTime or anything parsable by strtotime)

The date the state machine alias was created.

stateMachineAliasArn
Required: Yes
Type: string

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

Errors

InvalidArn:

The provided Amazon Resource Name (ARN) is not valid.

InvalidName:

The provided name is not valid.

ValidationException:

The input does not satisfy the constraints specified by an Amazon Web Services service.

StateMachineDeleting:

The specified state machine is being deleted.

ResourceNotFound:

Could not find the referenced resource.

ConflictException:

Updating or deleting a resource can cause an inconsistent state. This error occurs when there're concurrent requests for DeleteStateMachineVersion, PublishStateMachineVersion, or UpdateStateMachine with the publish parameter set to true.

HTTP Status Code: 409

ServiceQuotaExceededException:

The request would cause a service quota to be exceeded.

HTTP Status Code: 402

DeleteActivity

$result = $client->deleteActivity([/* ... */]);
$promise = $client->deleteActivityAsync([/* ... */]);

Deletes an activity.

Parameter Syntax

$result = $client->deleteActivity([
    'activityArn' => '<string>', // REQUIRED
]);

Parameter Details

Members
activityArn
Required: Yes
Type: string

The Amazon Resource Name (ARN) of the activity to delete.

Result Syntax

[]

Result Details

The results for this operation are always empty.

Errors

InvalidArn:

The provided Amazon Resource Name (ARN) is not valid.

DeleteStateMachine

$result = $client->deleteStateMachine([/* ... */]);
$promise = $client->deleteStateMachineAsync([/* ... */]);

Deletes a state machine. This is an asynchronous operation. It sets the state machine's status to DELETING and begins the deletion process. A state machine is deleted only when all its executions are completed. On the next state transition, the state machine's executions are terminated.

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

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

  • The following unqualified state machine ARN refers to a state machine named myStateMachine.

    arn:partition:states:region:account-id:stateMachine:myStateMachine

This API action also deletes all versions and aliases associated with a state machine.

For EXPRESS state machines, the deletion happens eventually (usually in less than a minute). Running executions may emit logs after DeleteStateMachine API is called.

Parameter Syntax

$result = $client->deleteStateMachine([
    'stateMachineArn' => '<string>', // REQUIRED
]);

Parameter Details

Members
stateMachineArn
Required: Yes
Type: string

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

Result Syntax

[]

Result Details

The results for this operation are always empty.

Errors

InvalidArn:

The provided Amazon Resource Name (ARN) is not valid.

ValidationException:

The input does not satisfy the constraints specified by an Amazon Web Services service.

DeleteStateMachineAlias

$result = $client->deleteStateMachineAlias([/* ... */]);
$promise = $client->deleteStateMachineAliasAsync([/* ... */]);

Deletes a state machine alias.

After you delete a state machine alias, you can't use it to start executions. When you delete a state machine alias, Step Functions doesn't delete the state machine versions that alias references.

Related operations:

Parameter Syntax

$result = $client->deleteStateMachineAlias([
    'stateMachineAliasArn' => '<string>', // REQUIRED
]);

Parameter Details

Members
stateMachineAliasArn
Required: Yes
Type: string

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

Result Syntax

[]

Result Details

The results for this operation are always empty.

Errors

ValidationException:

The input does not satisfy the constraints specified by an Amazon Web Services service.

InvalidArn:

The provided Amazon Resource Name (ARN) is not valid.

ResourceNotFound:

Could not find the referenced resource.

ConflictException:

Updating or deleting a resource can cause an inconsistent state. This error occurs when there're concurrent requests for DeleteStateMachineVersion, PublishStateMachineVersion, or UpdateStateMachine with the publish parameter set to true.

HTTP Status Code: 409

DeleteStateMachineVersion

$result = $client->deleteStateMachineVersion([/* ... */]);
$promise = $client->deleteStateMachineVersionAsync([/* ... */]);

Deletes a state machine version. After you delete a version, you can't call StartExecution using that version's ARN or use the version with a state machine alias.

Deleting a state machine version won't terminate its in-progress executions.

You can't delete a state machine version currently referenced by one or more aliases. Before you delete a version, you must either delete the aliases or update them to point to another state machine version.

Related operations:

Parameter Syntax

$result = $client->deleteStateMachineVersion([
    'stateMachineVersionArn' => '<string>', // REQUIRED
]);

Parameter Details

Members
stateMachineVersionArn
Required: Yes
Type: string

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

Result Syntax

[]

Result Details

The results for this operation are always empty.

Errors

ValidationException:

The input does not satisfy the constraints specified by an Amazon Web Services service.

InvalidArn:

The provided Amazon Resource Name (ARN) is not valid.

ConflictException:

Updating or deleting a resource can cause an inconsistent state. This error occurs when there're concurrent requests for DeleteStateMachineVersion, PublishStateMachineVersion, or UpdateStateMachine with the publish parameter set to true.

HTTP Status Code: 409

DescribeActivity

$result = $client->describeActivity([/* ... */]);
$promise = $client->describeActivityAsync([/* ... */]);

Describes an activity.

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

Parameter Syntax

$result = $client->describeActivity([
    'activityArn' => '<string>', // REQUIRED
]);

Parameter Details

Members
activityArn
Required: Yes
Type: string

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

Result Syntax

[
    'activityArn' => '<string>',
    'creationDate' => <DateTime>,
    'encryptionConfiguration' => [
        'kmsDataKeyReusePeriodSeconds' => <integer>,
        'kmsKeyId' => '<string>',
        'type' => 'AWS_OWNED_KEY|CUSTOMER_MANAGED_KMS_KEY',
    ],
    'name' => '<string>',
]

Result Details

Members
activityArn
Required: Yes
Type: string

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

creationDate
Required: Yes
Type: timestamp (string|DateTime or anything parsable by strtotime)

The date the activity is created.

encryptionConfiguration
Type: EncryptionConfiguration structure

Settings for configured server-side encryption.

name
Required: Yes
Type: string

The name of the activity.

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

Errors

ActivityDoesNotExist:

The specified activity does not exist.

InvalidArn:

The provided Amazon Resource Name (ARN) is not valid.

DescribeExecution

$result = $client->describeExecution([/* ... */]);
$promise = $client->describeExecutionAsync([/* ... */]);

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. If you've redriven an execution, you can use this API action to return information about the redrives of that execution. In addition, you can 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.

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

Executions of an EXPRESS state machine aren't supported by DescribeExecution unless a Map Run dispatched them.

Parameter Syntax

$result = $client->describeExecution([
    'executionArn' => '<string>', // REQUIRED
    'includedData' => 'ALL_DATA|METADATA_ONLY',
]);

Parameter Details

Members
executionArn
Required: Yes
Type: string

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

includedData
Type: string

If your state machine definition is encrypted with a KMS key, callers must have kms:Decrypt permission to decrypt the definition. Alternatively, you can call DescribeStateMachine API with includedData = METADATA_ONLY to get a successful response without the encrypted definition.

Result Syntax

[
    'cause' => '<string>',
    'error' => '<string>',
    'executionArn' => '<string>',
    'input' => '<string>',
    'inputDetails' => [
        'included' => true || false,
    ],
    'mapRunArn' => '<string>',
    'name' => '<string>',
    'output' => '<string>',
    'outputDetails' => [
        'included' => true || false,
    ],
    'redriveCount' => <integer>,
    'redriveDate' => <DateTime>,
    'redriveStatus' => 'REDRIVABLE|NOT_REDRIVABLE|REDRIVABLE_BY_MAP_RUN',
    'redriveStatusReason' => '<string>',
    'startDate' => <DateTime>,
    'stateMachineAliasArn' => '<string>',
    'stateMachineArn' => '<string>',
    'stateMachineVersionArn' => '<string>',
    'status' => 'RUNNING|SUCCEEDED|FAILED|TIMED_OUT|ABORTED|PENDING_REDRIVE',
    'stopDate' => <DateTime>,
    'traceHeader' => '<string>',
]

Result Details

Members
cause
Type: string

The cause string if the state machine execution failed.

error
Type: string

The error string if the state machine execution failed.

executionArn
Required: Yes
Type: string

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

input
Type: 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

Provides details about execution input or output.

mapRunArn
Type: string

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

name
Type: 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 _.

output
Type: string

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

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

outputDetails

Provides details about execution input or output.

redriveCount
Type: int

The number of times you've redriven an execution. If you have not yet redriven an execution, the redriveCount is 0. This count is only updated if you successfully redrive an execution.

redriveDate
Type: timestamp (string|DateTime or anything parsable by strtotime)

The date the execution was last redriven. If you have not yet redriven an execution, the redriveDate is null.

The redriveDate is unavailable if you redrive a Map Run that starts child workflow executions of type EXPRESS.

redriveStatus
Type: string

Indicates whether or not an execution can be redriven at a given point in time.

  • For executions of type STANDARD, redriveStatus is NOT_REDRIVABLE if calling the RedriveExecution API action would return the ExecutionNotRedrivable error.

  • For a Distributed Map that includes child workflows of type STANDARD, redriveStatus indicates whether or not the Map Run can redrive child workflow executions.

  • For a Distributed Map that includes child workflows of type EXPRESS, redriveStatus indicates whether or not the Map Run can redrive child workflow executions.

    You can redrive failed or timed out EXPRESS workflows only if they're a part of a Map Run. When you redrive the Map Run, these workflows are restarted using the StartExecution API action.

redriveStatusReason
Type: string

When redriveStatus is NOT_REDRIVABLE, redriveStatusReason specifies the reason why an execution cannot be redriven.

  • For executions of type STANDARD, or for a Distributed Map that includes child workflows of type STANDARD, redriveStatusReason can include one of the following reasons:

    • State machine is in DELETING status.

    • Execution is RUNNING and cannot be redriven.

    • Execution is SUCCEEDED and cannot be redriven.

    • Execution was started before the launch of RedriveExecution.

    • Execution history event limit exceeded.

    • Execution has exceeded the max execution time.

    • Execution redrivable period exceeded.

  • For a Distributed Map that includes child workflows of type EXPRESS, redriveStatusReason is only returned if the child workflows are not redrivable. This happens when the child workflow executions have completed successfully.

startDate
Required: Yes
Type: timestamp (string|DateTime or anything parsable by strtotime)

The date the execution is started.

stateMachineAliasArn
Type: 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.

stateMachineArn
Required: Yes
Type: string

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

stateMachineVersionArn
Type: 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.

status
Required: Yes
Type: string

The current status of the execution.

stopDate
Type: timestamp (string|DateTime or anything parsable by strtotime)

If the execution ended, the date the execution stopped.

traceHeader
Type: string

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

Errors

ExecutionDoesNotExist:

The specified execution does not exist.

InvalidArn:

The provided Amazon Resource Name (ARN) is not valid.

KmsAccessDeniedException:

Either your KMS key policy or API caller does not have the required permissions.

KmsInvalidStateException:

The KMS key is not in valid state, for example: Disabled or Deleted.

KmsThrottlingException:

Received when KMS returns ThrottlingException for a KMS call that Step Functions makes on behalf of the caller.

DescribeMapRun

$result = $client->describeMapRun([/* ... */]);
$promise = $client->describeMapRunAsync([/* ... */]);

Provides information about a Map Run's configuration, progress, and results. If you've redriven a Map Run, this API action also returns information about the redrives of that Map Run. For more information, see Examining Map Run in the Step Functions Developer Guide.

Parameter Syntax

$result = $client->describeMapRun([
    'mapRunArn' => '<string>', // REQUIRED
]);

Parameter Details

Members
mapRunArn
Required: Yes
Type: string

The Amazon Resource Name (ARN) that identifies a Map Run.

Result Syntax

[
    'executionArn' => '<string>',
    'executionCounts' => [
        'aborted' => <integer>,
        'failed' => <integer>,
        'failuresNotRedrivable' => <integer>,
        'pending' => <integer>,
        'pendingRedrive' => <integer>,
        'resultsWritten' => <integer>,
        'running' => <integer>,
        'succeeded' => <integer>,
        'timedOut' => <integer>,
        'total' => <integer>,
    ],
    'itemCounts' => [
        'aborted' => <integer>,
        'failed' => <integer>,
        'failuresNotRedrivable' => <integer>,
        'pending' => <integer>,
        'pendingRedrive' => <integer>,
        'resultsWritten' => <integer>,
        'running' => <integer>,
        'succeeded' => <integer>,
        'timedOut' => <integer>,
        'total' => <integer>,
    ],
    'mapRunArn' => '<string>',
    'maxConcurrency' => <integer>,
    'redriveCount' => <integer>,
    'redriveDate' => <DateTime>,
    'startDate' => <DateTime>,
    'status' => 'RUNNING|SUCCEEDED|FAILED|ABORTED',
    'stopDate' => <DateTime>,
    'toleratedFailureCount' => <integer>,
    'toleratedFailurePercentage' => <float>,
]

Result Details

Members
executionArn
Required: Yes
Type: string

The Amazon Resource Name (ARN) that identifies the execution in which the Map Run was started.

executionCounts
Required: Yes
Type: MapRunExecutionCounts structure

A JSON object that contains information about the total number of child workflow executions for the Map Run, and the count of child workflow executions for each status, such as failed and succeeded.

itemCounts
Required: Yes
Type: MapRunItemCounts structure

A JSON object that contains information about the total number of items, and the item count for each processing status, such as pending and failed.

mapRunArn
Required: Yes
Type: string

The Amazon Resource Name (ARN) that identifies a Map Run.

maxConcurrency
Required: Yes
Type: int

The maximum number of child workflow executions configured to run in parallel for the Map Run at the same time.

redriveCount
Type: int

The number of times you've redriven a Map Run. If you have not yet redriven a Map Run, the redriveCount is 0. This count is only updated if you successfully redrive a Map Run.

redriveDate
Type: timestamp (string|DateTime or anything parsable by strtotime)

The date a Map Run was last redriven. If you have not yet redriven a Map Run, the redriveDate is null.

startDate
Required: Yes
Type: timestamp (string|DateTime or anything parsable by strtotime)

The date when the Map Run was started.

status
Required: Yes
Type: string

The current status of the Map Run.

stopDate
Type: timestamp (string|DateTime or anything parsable by strtotime)

The date when the Map Run was stopped.

toleratedFailureCount
Required: Yes
Type: long (int|float)

The maximum number of failed child workflow executions before the Map Run fails.

toleratedFailurePercentage
Required: Yes
Type: float

The maximum percentage of failed child workflow executions before the Map Run fails.

Errors

ResourceNotFound:

Could not find the referenced resource.

InvalidArn:

The provided Amazon Resource Name (ARN) is not valid.

DescribeStateMachine

$result = $client->describeStateMachine([/* ... */]);
$promise = $client->describeStateMachineAsync([/* ... */]);

Provides information about a state machine's definition, its IAM role Amazon Resource Name (ARN), and configuration.

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

    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>

    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>

This API action returns the details for a state machine version if the stateMachineArn you specify is a state machine version ARN.

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

Parameter Syntax

$result = $client->describeStateMachine([
    'includedData' => 'ALL_DATA|METADATA_ONLY',
    'stateMachineArn' => '<string>', // REQUIRED
]);

Parameter Details

Members
includedData
Type: string

If your state machine definition is encrypted with a KMS key, callers must have kms:Decrypt permission to decrypt the definition. Alternatively, you can call the API with includedData = METADATA_ONLY to get a successful response without the encrypted definition.

When calling a labelled ARN for an encrypted state machine, the includedData = METADATA_ONLY parameter will not apply because Step Functions needs to decrypt the entire state machine definition to get the Distributed Map state’s definition. In this case, the API caller needs to have kms:Decrypt permission.

stateMachineArn
Required: Yes
Type: string

The Amazon Resource Name (ARN) of the state machine for which you want the information.

If you specify a state machine version ARN, this API returns details about that version. The version ARN is a combination of state machine ARN and the version number separated by a colon (:). For example, stateMachineARN:1.

Result Syntax

[
    'creationDate' => <DateTime>,
    'definition' => '<string>',
    'description' => '<string>',
    'encryptionConfiguration' => [
        'kmsDataKeyReusePeriodSeconds' => <integer>,
        'kmsKeyId' => '<string>',
        'type' => 'AWS_OWNED_KEY|CUSTOMER_MANAGED_KMS_KEY',
    ],
    'label' => '<string>',
    'loggingConfiguration' => [
        'destinations' => [
            [
                'cloudWatchLogsLogGroup' => [
                    'logGroupArn' => '<string>',
                ],
            ],
            // ...
        ],
        'includeExecutionData' => true || false,
        'level' => 'ALL|ERROR|FATAL|OFF',
    ],
    'name' => '<string>',
    'revisionId' => '<string>',
    'roleArn' => '<string>',
    'stateMachineArn' => '<string>',
    'status' => 'ACTIVE|DELETING',
    'tracingConfiguration' => [
        'enabled' => true || false,
    ],
    'type' => 'STANDARD|EXPRESS',
]

Result Details

Members
creationDate
Required: Yes
Type: timestamp (string|DateTime or anything parsable by strtotime)

The date the state machine is created.

For a state machine version, creationDate is the date the version was created.

definition
Required: Yes
Type: string

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

If called with includedData = METADATA_ONLY, the returned definition will be {}.

description
Type: string

The description of the state machine version.

encryptionConfiguration
Type: EncryptionConfiguration structure

Settings to configure server-side encryption.

label
Type: 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.

loggingConfiguration
Type: LoggingConfiguration structure

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

name
Required: Yes
Type: 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 _.

revisionId
Type: string

The revision identifier for the state machine.

Use the revisionId parameter to compare between versions of a state machine configuration used for executions without performing a diff of the properties, such as definition and roleArn.

roleArn
Required: Yes
Type: 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.)

stateMachineArn
Required: Yes
Type: string

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

If you specified a state machine version ARN in your request, the API returns the version ARN. The version ARN is a combination of state machine ARN and the version number separated by a colon (:). For example, stateMachineARN:1.

status
Type: string

The current status of the state machine.

tracingConfiguration
Type: TracingConfiguration structure

Selects whether X-Ray tracing is enabled.

type
Required: Yes
Type: string

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

Errors

InvalidArn:

The provided Amazon Resource Name (ARN) is not valid.

StateMachineDoesNotExist:

The specified state machine does not exist.

KmsAccessDeniedException:

Either your KMS key policy or API caller does not have the required permissions.

KmsInvalidStateException:

The KMS key is not in valid state, for example: Disabled or Deleted.

KmsThrottlingException:

Received when KMS returns ThrottlingException for a KMS call that Step Functions makes on behalf of the caller.

DescribeStateMachineAlias

$result = $client->describeStateMachineAlias([/* ... */]);
$promise = $client->describeStateMachineAliasAsync([/* ... */]);

Returns details about a state machine alias.

Related operations:

Parameter Syntax

$result = $client->describeStateMachineAlias([
    'stateMachineAliasArn' => '<string>', // REQUIRED
]);

Parameter Details

Members
stateMachineAliasArn
Required: Yes
Type: string

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

Result Syntax

[
    'creationDate' => <DateTime>,
    'description' => '<string>',
    'name' => '<string>',
    'routingConfiguration' => [
        [
            'stateMachineVersionArn' => '<string>',
            'weight' => <integer>,
        ],
        // ...
    ],
    'stateMachineAliasArn' => '<string>',
    'updateDate' => <DateTime>,
]

Result Details

Members
creationDate
Type: timestamp (string|DateTime or anything parsable by strtotime)

The date the state machine alias was created.

description
Type: string

A description of the alias.

name
Type: string

The name of the state machine alias.

routingConfiguration
Type: Array of RoutingConfigurationListItem structures

The routing configuration of the alias.

stateMachineAliasArn
Type: string

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

updateDate
Type: timestamp (string|DateTime or anything parsable by strtotime)

The date the state machine alias was last updated.

For a newly created state machine, this is the same as the creation date.

Errors

ValidationException:

The input does not satisfy the constraints specified by an Amazon Web Services service.

InvalidArn:

The provided Amazon Resource Name (ARN) is not valid.

ResourceNotFound:

Could not find the referenced resource.

DescribeStateMachineForExecution

$result = $client->describeStateMachineForExecution([/* ... */]);
$promise = $client->describeStateMachineForExecutionAsync([/* ... */]);

Provides information about a state machine's definition, its execution role ARN, and configuration. If a Map Run dispatched the execution, this action returns the Map Run Amazon Resource Name (ARN) in the response. The state machine returned is the state machine associated with the Map Run.

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

This API action is not supported by EXPRESS state machines.

Parameter Syntax

$result = $client->describeStateMachineForExecution([
    'executionArn' => '<string>', // REQUIRED
    'includedData' => 'ALL_DATA|METADATA_ONLY',
]);

Parameter Details

Members
executionArn
Required: Yes
Type: string

The Amazon Resource Name (ARN) of the execution you want state machine information for.

includedData
Type: string

If your state machine definition is encrypted with a KMS key, callers must have kms:Decrypt permission to decrypt the definition. Alternatively, you can call the API with includedData = METADATA_ONLY to get a successful response without the encrypted definition.

Result Syntax

[
    'definition' => '<string>',
    'encryptionConfiguration' => [
        'kmsDataKeyReusePeriodSeconds' => <integer>,
        'kmsKeyId' => '<string>',
        'type' => 'AWS_OWNED_KEY|CUSTOMER_MANAGED_KMS_KEY',
    ],
    'label' => '<string>',
    'loggingConfiguration' => [
        'destinations' => [
            [
                'cloudWatchLogsLogGroup' => [
                    'logGroupArn' => '<string>',
                ],
            ],
            // ...
        ],
        'includeExecutionData' => true || false,
        'level' => 'ALL|ERROR|FATAL|OFF',
    ],
    'mapRunArn' => '<string>',
    'name' => '<string>',
    'revisionId' => '<string>',
    'roleArn' => '<string>',
    'stateMachineArn' => '<string>',
    'tracingConfiguration' => [
        'enabled' => true || false,
    ],
    'updateDate' => <DateTime>,
]

Result Details

Members
definition
Required: Yes
Type: string

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

encryptionConfiguration
Type: EncryptionConfiguration structure

Settings to configure server-side encryption.

label
Type: string

A user-defined or an auto-generated string that identifies a Map state. This field is returned only if the executionArn is a child workflow execution that was started by a Distributed Map state.

loggingConfiguration
Type: LoggingConfiguration structure

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

mapRunArn
Type: string

The Amazon Resource Name (ARN) of the Map Run that started the child workflow execution. This field is returned only if the executionArn is a child workflow execution that was started by a Distributed Map state.

name
Required: Yes
Type: string

The name of the state machine associated with the execution.

revisionId
Type: string

The revision identifier for the state machine. The first revision ID when you create the state machine is null.

Use the state machine revisionId parameter to compare the revision of a state machine with the configuration of the state machine used for executions without performing a diff of the properties, such as definition and roleArn.

roleArn
Required: Yes
Type: string

The Amazon Resource Name (ARN) of the IAM role of the State Machine for the execution.

stateMachineArn
Required: Yes
Type: string

The Amazon Resource Name (ARN) of the state machine associated with the execution.

tracingConfiguration
Type: TracingConfiguration structure

Selects whether X-Ray tracing is enabled.

updateDate
Required: Yes
Type: timestamp (string|DateTime or anything parsable by strtotime)

The date and time the state machine associated with an execution was updated. For a newly created state machine, this is the creation date.

Errors

ExecutionDoesNotExist:

The specified execution does not exist.

InvalidArn:

The provided Amazon Resource Name (ARN) is not valid.

KmsAccessDeniedException:

Either your KMS key policy or API caller does not have the required permissions.

KmsInvalidStateException:

The KMS key is not in valid state, for example: Disabled or Deleted.

KmsThrottlingException:

Received when KMS returns ThrottlingException for a KMS call that Step Functions makes on behalf of the caller.

GetActivityTask

$result = $client->getActivityTask([/* ... */]);
$promise = $client->getActivityTaskAsync([/* ... */]);

Used by workers to retrieve a task (with the specified activity ARN) which has been scheduled for execution by a running state machine. This initiates a long poll, where the service holds the HTTP connection open and responds as soon as a task becomes available (i.e. an execution of a task of this type is needed.) The maximum time the service holds on to the request before responding is 60 seconds. If no task is available within 60 seconds, the poll returns a taskToken with a null string.

This API action isn't logged in CloudTrail.

Workers should set their client side socket timeout to at least 65 seconds (5 seconds higher than the maximum time the service may hold the poll request).

Polling with GetActivityTask can cause latency in some implementations. See Avoid Latency When Polling for Activity Tasks in the Step Functions Developer Guide.

Parameter Syntax

$result = $client->getActivityTask([
    'activityArn' => '<string>', // REQUIRED
    'workerName' => '<string>',
]);

Parameter Details

Members
activityArn
Required: Yes
Type: string

The Amazon Resource Name (ARN) of the activity to retrieve tasks from (assigned when you create the task using CreateActivity.)

workerName
Type: string

You can provide an arbitrary name in order to identify the worker that the task is assigned to. This name is used when it is logged in the execution history.

Result Syntax

[
    'input' => '<string>',
    'taskToken' => '<string>',
]

Result Details

Members
input
Type: string

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

taskToken
Type: string

A token that identifies the scheduled task. This token must be copied and included in subsequent calls to SendTaskHeartbeat, SendTaskSuccess or SendTaskFailure in order to report the progress or completion of the task.

Errors

ActivityDoesNotExist:

The specified activity does not exist.

ActivityWorkerLimitExceeded:

The maximum number of workers concurrently polling for activity tasks has been reached.

InvalidArn:

The provided Amazon Resource Name (ARN) is not valid.

KmsAccessDeniedException:

Either your KMS key policy or API caller does not have the required permissions.

KmsInvalidStateException:

The KMS key is not in valid state, for example: Disabled or Deleted.

KmsThrottlingException:

Received when KMS returns ThrottlingException for a KMS call that Step Functions makes on behalf of the caller.

GetExecutionHistory

$result = $client->getExecutionHistory([/* ... */]);
$promise = $client->getExecutionHistoryAsync([/* ... */]);

Returns the history of the specified execution as a list of events. By default, the results are returned in ascending order of the timeStamp of the events. Use the reverseOrder parameter to get the latest events first.

If nextToken is returned, there are more results available. The value of nextToken is a unique pagination token for each page. Make the call again using the returned token to retrieve the next page. Keep all other arguments unchanged. Each pagination token expires after 24 hours. Using an expired pagination token will return an HTTP 400 InvalidToken error.

This API action is not supported by EXPRESS state machines.

Parameter Syntax

$result = $client->getExecutionHistory([
    'executionArn' => '<string>', // REQUIRED
    'includeExecutionData' => true || false,
    'maxResults' => <integer>,
    'nextToken' => '<string>',
    'reverseOrder' => true || false,
]);

Parameter Details

Members
executionArn
Required: Yes
Type: string

The Amazon Resource Name (ARN) of the execution.

includeExecutionData
Type: boolean

You can select whether execution data (input or output of a history event) is returned. The default is true.

maxResults
Type: int

The maximum number of results that are returned per call. You can use nextToken to obtain further pages of results. The default is 100 and the maximum allowed page size is 1000. A value of 0 uses the default.

This is only an upper limit. The actual number of results returned per call might be fewer than the specified maximum.

nextToken
Type: string

If nextToken is returned, there are more results available. The value of nextToken is a unique pagination token for each page. Make the call again using the returned token to retrieve the next page. Keep all other arguments unchanged. Each pagination token expires after 24 hours. Using an expired pagination token will return an HTTP 400 InvalidToken error.

reverseOrder
Type: boolean

Lists events in descending order of their timeStamp.

Result Syntax

[
    'events' => [
        [
            'activityFailedEventDetails' => [
                'cause' => '<string>',
                'error' => '<string>',
            ],
            'activityScheduleFailedEventDetails' => [
                'cause' => '<string>',
                'error' => '<string>',
            ],
            'activityScheduledEventDetails' => [
                'heartbeatInSeconds' => <integer>,
                'input' => '<string>',
                'inputDetails' => [
                    'truncated' => true || false,
                ],
                'resource' => '<string>',
                'timeoutInSeconds' => <integer>,
            ],
            'activityStartedEventDetails' => [
                'workerName' => '<string>',
            ],
            'activitySucceededEventDetails' => [
                'output' => '<string>',
                'outputDetails' => [
                    'truncated' => true || false,
                ],
            ],
            'activityTimedOutEventDetails' => [
                'cause' => '<string>',
                'error' => '<string>',
            ],
            'executionAbortedEventDetails' => [
                'cause' => '<string>',
                'error' => '<string>',
            ],
            'executionFailedEventDetails' => [
                'cause' => '<string>',
                'error' => '<string>',
            ],
            'executionRedrivenEventDetails' => [
                'redriveCount' => <integer>,
            ],
            'executionStartedEventDetails' => [
                'input' => '<string>',
                'inputDetails' => [
                    'truncated' => true || false,
                ],
                'roleArn' => '<string>',
                'stateMachineAliasArn' => '<string>',
                'stateMachineVersionArn' => '<string>',
            ],
            'executionSucceededEventDetails' => [
                'output' => '<string>',
                'outputDetails' => [
                    'truncated' => true || false,
                ],
            ],
            'executionTimedOutEventDetails' => [
                'cause' => '<string>',
                'error' => '<string>',
            ],
            'id' => <integer>,
            'lambdaFunctionFailedEventDetails' => [
                'cause' => '<string>',
                'error' => '<string>',
            ],
            'lambdaFunctionScheduleFailedEventDetails' => [
                'cause' => '<string>',
                'error' => '<string>',
            ],
            'lambdaFunctionScheduledEventDetails' => [
                'input' => '<string>',
                'inputDetails' => [
                    'truncated' => true || false,
                ],
                'resource' => '<string>',
                'taskCredentials' => [
                    'roleArn' => '<string>',
                ],
                'timeoutInSeconds' => <integer>,
            ],
            'lambdaFunctionStartFailedEventDetails' => [
                'cause' => '<string>',
                'error' => '<string>',
            ],
            'lambdaFunctionSucceededEventDetails' => [
                'output' => '<string>',
                'outputDetails' => [
                    'truncated' => true || false,
                ],
            ],
            'lambdaFunctionTimedOutEventDetails' => [
                'cause' => '<string>',
                'error' => '<string>',
            ],
            'mapIterationAbortedEventDetails' => [
                'index' => <integer>,
                'name' => '<string>',
            ],
            'mapIterationFailedEventDetails' => [
                'index' => <integer>,
                'name' => '<string>',
            ],
            'mapIterationStartedEventDetails' => [
                'index' => <integer>,
                'name' => '<string>',
            ],
            'mapIterationSucceededEventDetails' => [
                'index' => <integer>,
                'name' => '<string>',
            ],
            'mapRunFailedEventDetails' => [
                'cause' => '<string>',
                'error' => '<string>',
            ],
            'mapRunRedrivenEventDetails' => [
                'mapRunArn' => '<string>',
                'redriveCount' => <integer>,
            ],
            'mapRunStartedEventDetails' => [
                'mapRunArn' => '<string>',
            ],
            'mapStateStartedEventDetails' => [
                'length' => <integer>,
            ],
            'previousEventId' => <integer>,
            'stateEnteredEventDetails' => [
                'input' => '<string>',
                'inputDetails' => [
                    'truncated' => true || false,
                ],
                'name' => '<string>',
            ],
            'stateExitedEventDetails' => [
                'name' => '<string>',
                'output' => '<string>',
                'outputDetails' => [
                    'truncated' => true || false,
                ],
            ],
            'taskFailedEventDetails' => [
                'cause' => '<string>',
                'error' => '<string>',
                'resource' => '<string>',
                'resourceType' => '<string>',
            ],
            'taskScheduledEventDetails' => [
                'heartbeatInSeconds' => <integer>,
                'parameters' => '<string>',
                'region' => '<string>',
                'resource' => '<string>',
                'resourceType' => '<string>',
                'taskCredentials' => [
                    'roleArn' => '<string>',
                ],
                'timeoutInSeconds' => <integer>,
            ],
            'taskStartFailedEventDetails' => [
                'cause' => '<string>',
                'error' => '<string>',
                'resource' => '<string>',
                'resourceType' => '<string>',
            ],
            'taskStartedEventDetails' => [
                'resource' => '<string>',
                'resourceType' => '<string>',
            ],
            'taskSubmitFailedEventDetails' => [
                'cause' => '<string>',
                'error' => '<string>',
                'resource' => '<string>',
                'resourceType' => '<string>',
            ],
            'taskSubmittedEventDetails' => [
                'output' => '<string>',
                'outputDetails' => [
                    'truncated' => true || false,
                ],
                'resource' => '<string>',
                'resourceType' => '<string>',
            ],
            'taskSucceededEventDetails' => [
                'output' => '<string>',
                'outputDetails' => [
                    'truncated' => true || false,
                ],
                'resource' => '<string>',
                'resourceType' => '<string>',
            ],
            'taskTimedOutEventDetails' => [
                'cause' => '<string>',
                'error' => '<string>',
                'resource' => '<string>',
                'resourceType' => '<string>',
            ],
            'timestamp' => <DateTime>,
            'type' => 'ActivityFailed|ActivityScheduled|ActivityScheduleFailed|ActivityStarted|ActivitySucceeded|ActivityTimedOut|ChoiceStateEntered|ChoiceStateExited|ExecutionAborted|ExecutionFailed|ExecutionStarted|ExecutionSucceeded|ExecutionTimedOut|FailStateEntered|LambdaFunctionFailed|LambdaFunctionScheduled|LambdaFunctionScheduleFailed|LambdaFunctionStarted|LambdaFunctionStartFailed|LambdaFunctionSucceeded|LambdaFunctionTimedOut|MapIterationAborted|MapIterationFailed|MapIterationStarted|MapIterationSucceeded|MapStateAborted|MapStateEntered|MapStateExited|MapStateFailed|MapStateStarted|MapStateSucceeded|ParallelStateAborted|ParallelStateEntered|ParallelStateExited|ParallelStateFailed|ParallelStateStarted|ParallelStateSucceeded|PassStateEntered|PassStateExited|SucceedStateEntered|SucceedStateExited|TaskFailed|TaskScheduled|TaskStarted|TaskStartFailed|TaskStateAborted|TaskStateEntered|TaskStateExited|TaskSubmitFailed|TaskSubmitted|TaskSucceeded|TaskTimedOut|WaitStateAborted|WaitStateEntered|WaitStateExited|MapRunAborted|MapRunFailed|MapRunStarted|MapRunSucceeded|ExecutionRedriven|MapRunRedriven',
        ],
        // ...
    ],
    'nextToken' => '<string>',
]

Result Details

Members
events
Required: Yes
Type: Array of HistoryEvent structures

The list of events that occurred in the execution.

nextToken
Type: string

If nextToken is returned, there are more results available. The value of nextToken is a unique pagination token for each page. Make the call again using the returned token to retrieve the next page. Keep all other arguments unchanged. Each pagination token expires after 24 hours. Using an expired pagination token will return an HTTP 400 InvalidToken error.

Errors

ExecutionDoesNotExist:

The specified execution does not exist.

InvalidArn:

The provided Amazon Resource Name (ARN) is not valid.

InvalidToken:

The provided token is not valid.

KmsAccessDeniedException:

Either your KMS key policy or API caller does not have the required permissions.

KmsInvalidStateException:

The KMS key is not in valid state, for example: Disabled or Deleted.

KmsThrottlingException:

Received when KMS returns ThrottlingException for a KMS call that Step Functions makes on behalf of the caller.

ListActivities

$result = $client->listActivities([/* ... */]);
$promise = $client->listActivitiesAsync([/* ... */]);

Lists the existing activities.

If nextToken is returned, there are more results available. The value of nextToken is a unique pagination token for each page. Make the call again using the returned token to retrieve the next page. Keep all other arguments unchanged. Each pagination token expires after 24 hours. Using an expired pagination token will return an HTTP 400 InvalidToken error.

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

Parameter Syntax

$result = $client->listActivities([
    'maxResults' => <integer>,
    'nextToken' => '<string>',
]);

Parameter Details

Members
maxResults
Type: int

The maximum number of results that are returned per call. You can use nextToken to obtain further pages of results. The default is 100 and the maximum allowed page size is 1000. A value of 0 uses the default.

This is only an upper limit. The actual number of results returned per call might be fewer than the specified maximum.

nextToken
Type: string

If nextToken is returned, there are more results available. The value of nextToken is a unique pagination token for each page. Make the call again using the returned token to retrieve the next page. Keep all other arguments unchanged. Each pagination token expires after 24 hours. Using an expired pagination token will return an HTTP 400 InvalidToken error.

Result Syntax

[
    'activities' => [
        [
            'activityArn' => '<string>',
            'creationDate' => <DateTime>,
            'name' => '<string>',
        ],
        // ...
    ],
    'nextToken' => '<string>',
]

Result Details

Members
activities
Required: Yes
Type: Array of ActivityListItem structures

The list of activities.

nextToken
Type: string

If nextToken is returned, there are more results available. The value of nextToken is a unique pagination token for each page. Make the call again using the returned token to retrieve the next page. Keep all other arguments unchanged. Each pagination token expires after 24 hours. Using an expired pagination token will return an HTTP 400 InvalidToken error.

Errors

InvalidToken:

The provided token is not valid.

ListExecutions

$result = $client->listExecutions([/* ... */]);
$promise = $client->listExecutionsAsync([/* ... */]);

Lists all executions of a state machine or a Map Run. You can list all executions related to a state machine by specifying a state machine Amazon Resource Name (ARN), or those related to a Map Run by specifying a Map Run ARN. Using this API action, you can also list all redriven executions.

You can also provide a state machine alias ARN or version ARN to list the executions associated with a specific alias or version.

Results are sorted by time, with the most recent execution first.

If nextToken is returned, there are more results available. The value of nextToken is a unique pagination token for each page. Make the call again using the returned token to retrieve the next page. Keep all other arguments unchanged. Each pagination token expires after 24 hours. Using an expired pagination token will return an HTTP 400 InvalidToken error.

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

This API action is not supported by EXPRESS state machines.

Parameter Syntax

$result = $client->listExecutions([
    'mapRunArn' => '<string>',
    'maxResults' => <integer>,
    'nextToken' => '<string>',
    'redriveFilter' => 'REDRIVEN|NOT_REDRIVEN',
    'stateMachineArn' => '<string>',
    'statusFilter' => 'RUNNING|SUCCEEDED|FAILED|TIMED_OUT|ABORTED|PENDING_REDRIVE',
]);

Parameter Details

Members
mapRunArn
Type: string

The Amazon Resource Name (ARN) of the Map Run that started the child workflow executions. If the mapRunArn field is specified, a list of all of the child workflow executions started by a Map Run is returned. For more information, see Examining Map Run in the Step Functions Developer Guide.

You can specify either a mapRunArn or a stateMachineArn, but not both.

maxResults
Type: int

The maximum number of results that are returned per call. You can use nextToken to obtain further pages of results. The default is 100 and the maximum allowed page size is 1000. A value of 0 uses the default.

This is only an upper limit. The actual number of results returned per call might be fewer than the specified maximum.

nextToken
Type: string

If nextToken is returned, there are more results available. The value of nextToken is a unique pagination token for each page. Make the call again using the returned token to retrieve the next page. Keep all other arguments unchanged. Each pagination token expires after 24 hours. Using an expired pagination token will return an HTTP 400 InvalidToken error.

redriveFilter
Type: string

Sets a filter to list executions based on whether or not they have been redriven.

For a Distributed Map, redriveFilter sets a filter to list child workflow executions based on whether or not they have been redriven.

If you do not provide a redriveFilter, Step Functions returns a list of both redriven and non-redriven executions.

If you provide a state machine ARN in redriveFilter, the API returns a validation exception.

stateMachineArn
Type: string

The Amazon Resource Name (ARN) of the state machine whose executions is listed.

You can specify either a mapRunArn or a stateMachineArn, but not both.

You can also return a list of executions associated with a specific alias or version, by specifying an alias ARN or a version ARN in the stateMachineArn parameter.

statusFilter
Type: string

If specified, only list the executions whose current execution status matches the given filter.

Result Syntax

[
    'executions' => [
        [
            'executionArn' => '<string>',
            'itemCount' => <integer>,
            'mapRunArn' => '<string>',
            'name' => '<string>',
            'redriveCount' => <integer>,
            'redriveDate' => <DateTime>,
            'startDate' => <DateTime>,
            'stateMachineAliasArn' => '<string>',
            'stateMachineArn' => '<string>',
            'stateMachineVersionArn' => '<string>',
            'status' => 'RUNNING|SUCCEEDED|FAILED|TIMED_OUT|ABORTED|PENDING_REDRIVE',
            'stopDate' => <DateTime>,
        ],
        // ...
    ],
    'nextToken' => '<string>',
]

Result Details

Members
executions
Required: Yes
Type: Array of ExecutionListItem structures

The list of matching executions.

nextToken
Type: string

If nextToken is returned, there are more results available. The value of nextToken is a unique pagination token for each page. Make the call again using the returned token to retrieve the next page. Keep all other arguments unchanged. Each pagination token expires after 24 hours. Using an expired pagination token will return an HTTP 400 InvalidToken error.

Errors

InvalidArn:

The provided Amazon Resource Name (ARN) is not valid.

InvalidToken:

The provided token is not valid.

StateMachineDoesNotExist:

The specified state machine does not exist.

StateMachineTypeNotSupported:

State machine type is not supported.

ValidationException:

The input does not satisfy the constraints specified by an Amazon Web Services service.

ResourceNotFound:

Could not find the referenced resource.

ListMapRuns

$result = $client->listMapRuns([/* ... */]);
$promise = $client->listMapRunsAsync([/* ... */]);

Lists all Map Runs that were started by a given state machine execution. Use this API action to obtain Map Run ARNs, and then call DescribeMapRun to obtain more information, if needed.

Parameter Syntax

$result = $client->listMapRuns([
    'executionArn' => '<string>', // REQUIRED
    'maxResults' => <integer>,
    'nextToken' => '<string>',
]);

Parameter Details

Members
executionArn
Required: Yes
Type: string

The Amazon Resource Name (ARN) of the execution for which the Map Runs must be listed.

maxResults
Type: int

The maximum number of results that are returned per call. You can use nextToken to obtain further pages of results. The default is 100 and the maximum allowed page size is 1000. A value of 0 uses the default.

This is only an upper limit. The actual number of results returned per call might be fewer than the specified maximum.

nextToken
Type: string

If nextToken is returned, there are more results available. The value of nextToken is a unique pagination token for each page. Make the call again using the returned token to retrieve the next page. Keep all other arguments unchanged. Each pagination token expires after 24 hours. Using an expired pagination token will return an HTTP 400 InvalidToken error.

Result Syntax

[
    'mapRuns' => [
        [
            'executionArn' => '<string>',
            'mapRunArn' => '<string>',
            'startDate' => <DateTime>,
            'stateMachineArn' => '<string>',
            'stopDate' => <DateTime>,
        ],
        // ...
    ],
    'nextToken' => '<string>',
]

Result Details

Members
mapRuns
Required: Yes
Type: Array of MapRunListItem structures

An array that lists information related to a Map Run, such as the Amazon Resource Name (ARN) of the Map Run and the ARN of the state machine that started the Map Run.

nextToken
Type: string

If nextToken is returned, there are more results available. The value of nextToken is a unique pagination token for each page. Make the call again using the returned token to retrieve the next page. Keep all other arguments unchanged. Each pagination token expires after 24 hours. Using an expired pagination token will return an HTTP 400 InvalidToken error.

Errors

ExecutionDoesNotExist:

The specified execution does not exist.

InvalidArn:

The provided Amazon Resource Name (ARN) is not valid.

InvalidToken:

The provided token is not valid.

ListStateMachineAliases

$result = $client->listStateMachineAliases([/* ... */]);
$promise = $client->listStateMachineAliasesAsync([/* ... */]);

Lists aliases for a specified state machine ARN. Results are sorted by time, with the most recently created aliases listed first.

To list aliases that reference a state machine version, you can specify the version ARN in the stateMachineArn parameter.

If nextToken is returned, there are more results available. The value of nextToken is a unique pagination token for each page. Make the call again using the returned token to retrieve the next page. Keep all other arguments unchanged. Each pagination token expires after 24 hours. Using an expired pagination token will return an HTTP 400 InvalidToken error.

Related operations:

Parameter Syntax

$result = $client->listStateMachineAliases([
    'maxResults' => <integer>,
    'nextToken' => '<string>',
    'stateMachineArn' => '<string>', // REQUIRED
]);

Parameter Details

Members
maxResults
Type: int

The maximum number of results that are returned per call. You can use nextToken to obtain further pages of results. The default is 100 and the maximum allowed page size is 1000. A value of 0 uses the default.

This is only an upper limit. The actual number of results returned per call might be fewer than the specified maximum.

nextToken
Type: string

If nextToken is returned, there are more results available. The value of nextToken is a unique pagination token for each page. Make the call again using the returned token to retrieve the next page. Keep all other arguments unchanged. Each pagination token expires after 24 hours. Using an expired pagination token will return an HTTP 400 InvalidToken error.

stateMachineArn
Required: Yes
Type: string

The Amazon Resource Name (ARN) of the state machine for which you want to list aliases.

If you specify a state machine version ARN, this API returns a list of aliases for that version.

Result Syntax

[
    'nextToken' => '<string>',
    'stateMachineAliases' => [
        [
            'creationDate' => <DateTime>,
            'stateMachineAliasArn' => '<string>',
        ],
        // ...
    ],
]

Result Details

Members
nextToken
Type: string

If nextToken is returned, there are more results available. The value of nextToken is a unique pagination token for each page. Make the call again using the returned token to retrieve the next page. Keep all other arguments unchanged. Each pagination token expires after 24 hours. Using an expired pagination token will return an HTTP 400 InvalidToken error.

stateMachineAliases
Required: Yes
Type: Array of StateMachineAliasListItem structures

Aliases for the state machine.

Errors

InvalidArn:

The provided Amazon Resource Name (ARN) is not valid.

InvalidToken:

The provided token is not valid.

ResourceNotFound:

Could not find the referenced resource.

StateMachineDoesNotExist:

The specified state machine does not exist.

StateMachineDeleting:

The specified state machine is being deleted.

ListStateMachineVersions

$result = $client->listStateMachineVersions([/* ... */]);
$promise = $client->listStateMachineVersionsAsync([/* ... */]);

Lists versions for the specified state machine Amazon Resource Name (ARN).

The results are sorted in descending order of the version creation time.

If nextToken is returned, there are more results available. The value of nextToken is a unique pagination token for each page. Make the call again using the returned token to retrieve the next page. Keep all other arguments unchanged. Each pagination token expires after 24 hours. Using an expired pagination token will return an HTTP 400 InvalidToken error.

Related operations:

Parameter Syntax

$result = $client->listStateMachineVersions([
    'maxResults' => <integer>,
    'nextToken' => '<string>',
    'stateMachineArn' => '<string>', // REQUIRED
]);

Parameter Details

Members
maxResults
Type: int

The maximum number of results that are returned per call. You can use nextToken to obtain further pages of results. The default is 100 and the maximum allowed page size is 1000. A value of 0 uses the default.

This is only an upper limit. The actual number of results returned per call might be fewer than the specified maximum.

nextToken
Type: string

If nextToken is returned, there are more results available. The value of nextToken is a unique pagination token for each page. Make the call again using the returned token to retrieve the next page. Keep all other arguments unchanged. Each pagination token expires after 24 hours. Using an expired pagination token will return an HTTP 400 InvalidToken error.

stateMachineArn
Required: Yes
Type: string

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

Result Syntax

[
    'nextToken' => '<string>',
    'stateMachineVersions' => [
        [
            'creationDate' => <DateTime>,
            'stateMachineVersionArn' => '<string>',
        ],
        // ...
    ],
]

Result Details

Members
nextToken
Type: string

If nextToken is returned, there are more results available. The value of nextToken is a unique pagination token for each page. Make the call again using the returned token to retrieve the next page. Keep all other arguments unchanged. Each pagination token expires after 24 hours. Using an expired pagination token will return an HTTP 400 InvalidToken error.

stateMachineVersions
Required: Yes
Type: Array of StateMachineVersionListItem structures

Versions for the state machine.

Errors

ValidationException:

The input does not satisfy the constraints specified by an Amazon Web Services service.

InvalidArn:

The provided Amazon Resource Name (ARN) is not valid.

InvalidToken:

The provided token is not valid.

ListStateMachines

$result = $client->listStateMachines([/* ... */]);
$promise = $client->listStateMachinesAsync([/* ... */]);

Lists the existing state machines.

If nextToken is returned, there are more results available. The value of nextToken is a unique pagination token for each page. Make the call again using the returned token to retrieve the next page. Keep all other arguments unchanged. Each pagination token expires after 24 hours. Using an expired pagination token will return an HTTP 400 InvalidToken error.

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

Parameter Syntax

$result = $client->listStateMachines([
    'maxResults' => <integer>,
    'nextToken' => '<string>',
]);

Parameter Details

Members
maxResults
Type: int

The maximum number of results that are returned per call. You can use nextToken to obtain further pages of results. The default is 100 and the maximum allowed page size is 1000. A value of 0 uses the default.

This is only an upper limit. The actual number of results returned per call might be fewer than the specified maximum.

nextToken
Type: string

If nextToken is returned, there are more results available. The value of nextToken is a unique pagination token for each page. Make the call again using the returned token to retrieve the next page. Keep all other arguments unchanged. Each pagination token expires after 24 hours. Using an expired pagination token will return an HTTP 400 InvalidToken error.

Result Syntax

[
    'nextToken' => '<string>',
    'stateMachines' => [
        [
            'creationDate' => <DateTime>,
            'name' => '<string>',
            'stateMachineArn' => '<string>',
            'type' => 'STANDARD|EXPRESS',
        ],
        // ...
    ],
]

Result Details

Members
nextToken
Type: string

If nextToken is returned, there are more results available. The value of nextToken is a unique pagination token for each page. Make the call again using the returned token to retrieve the next page. Keep all other arguments unchanged. Each pagination token expires after 24 hours. Using an expired pagination token will return an HTTP 400 InvalidToken error.

stateMachines
Required: Yes
Type: Array of StateMachineListItem structures

Errors

InvalidToken:

The provided token is not valid.

ListTagsForResource

$result = $client->listTagsForResource([/* ... */]);
$promise = $client->listTagsForResourceAsync([/* ... */]);

List tags for a given resource.

Tags may only contain Unicode letters, digits, white space, or these symbols: _ . : / = + - @.

Parameter Syntax

$result = $client->listTagsForResource([
    'resourceArn' => '<string>', // REQUIRED
]);

Parameter Details

Members
resourceArn
Required: Yes
Type: string

The Amazon Resource Name (ARN) for the Step Functions state machine or activity.

Result Syntax

[
    'tags' => [
        [
            'key' => '<string>',
            'value' => '<string>',
        ],
        // ...
    ],
]

Result Details

Members
tags
Type: Array of Tag structures

An array of tags associated with the resource.

Errors

InvalidArn:

The provided Amazon Resource Name (ARN) is not valid.

ResourceNotFound:

Could not find the referenced resource.

PublishStateMachineVersion

$result = $client->publishStateMachineVersion([/* ... */]);
$promise = $client->publishStateMachineVersionAsync([/* ... */]);

Creates a version from the current revision of a state machine. Use versions to create immutable snapshots of your state machine. You can start executions from versions either directly or with an alias. To create an alias, use CreateStateMachineAlias.

You can publish up to 1000 versions for each state machine. You must manually delete unused versions using the DeleteStateMachineVersion API action.

PublishStateMachineVersion is an idempotent API. It doesn't create a duplicate state machine version if it already exists for the current revision. Step Functions bases PublishStateMachineVersion's idempotency check on the stateMachineArn, name, and revisionId parameters. Requests with the same parameters return a successful idempotent response. If you don't specify a revisionId, Step Functions checks for a previously published version of the state machine's current revision.

Related operations:

Parameter Syntax

$result = $client->publishStateMachineVersion([
    'description' => '<string>',
    'revisionId' => '<string>',
    'stateMachineArn' => '<string>', // REQUIRED
]);

Parameter Details

Members
description
Type: string

An optional description of the state machine version.

revisionId
Type: string

Only publish the state machine version if the current state machine's revision ID matches the specified ID.

Use this option to avoid publishing a version if the state machine changed since you last updated it. If the specified revision ID doesn't match the state machine's current revision ID, the API returns ConflictException.

To specify an initial revision ID for a state machine with no revision ID assigned, specify the string INITIAL for the revisionId parameter. For example, you can specify a revisionID of INITIAL when you create a state machine using the CreateStateMachine API action.

stateMachineArn
Required: Yes
Type: string

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

Result Syntax

[
    'creationDate' => <DateTime>,
    'stateMachineVersionArn' => '<string>',
]

Result Details

Members
creationDate
Required: Yes
Type: timestamp (string|DateTime or anything parsable by strtotime)

The date the version was created.

stateMachineVersionArn
Required: Yes
Type: string

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

Errors

ValidationException:

The input does not satisfy the constraints specified by an Amazon Web Services service.

StateMachineDeleting:

The specified state machine is being deleted.

StateMachineDoesNotExist:

The specified state machine does not exist.

ServiceQuotaExceededException:

The request would cause a service quota to be exceeded.

HTTP Status Code: 402

ConflictException:

Updating or deleting a resource can cause an inconsistent state. This error occurs when there're concurrent requests for DeleteStateMachineVersion, PublishStateMachineVersion, or UpdateStateMachine with the publish parameter set to true.

HTTP Status Code: 409

InvalidArn:

The provided Amazon Resource Name (ARN) is not valid.

RedriveExecution

$result = $client->redriveExecution([/* ... */]);
$promise = $client->redriveExecutionAsync([/* ... */]);

Restarts unsuccessful executions of Standard workflows that didn't complete successfully in the last 14 days. These include failed, aborted, or timed out executions. When you redrive an execution, it continues the failed execution from the unsuccessful step and uses the same input. Step Functions preserves the results and execution history of the successful steps, and doesn't rerun these steps when you redrive an execution. Redriven executions use the same state machine definition and execution ARN as the original execution attempt.

For workflows that include an Inline Map or Parallel state, RedriveExecution API action reschedules and redrives only the iterations and branches that failed or aborted.

To redrive a workflow that includes a Distributed Map state whose Map Run failed, you must redrive the parent workflow. The parent workflow redrives all the unsuccessful states, including a failed Map Run. If a Map Run was not started in the original execution attempt, the redriven parent workflow starts the Map Run.

This API action is not supported by EXPRESS state machines.

However, you can restart the unsuccessful executions of Express child workflows in a Distributed Map by redriving its Map Run. When you redrive a Map Run, the Express child workflows are rerun using the StartExecution API action. For more information, see Redriving Map Runs.

You can redrive executions if your original execution meets the following conditions:

  • The execution status isn't SUCCEEDED.

  • Your workflow execution has not exceeded the redrivable period of 14 days. Redrivable period refers to the time during which you can redrive a given execution. This period starts from the day a state machine completes its execution.

  • The workflow execution has not exceeded the maximum open time of one year. For more information about state machine quotas, see Quotas related to state machine executions.

  • The execution event history count is less than 24,999. Redriven executions append their event history to the existing event history. Make sure your workflow execution contains less than 24,999 events to accommodate the ExecutionRedriven history event and at least one other history event.

Parameter Syntax

$result = $client->redriveExecution([
    'clientToken' => '<string>',
    'executionArn' => '<string>', // REQUIRED
]);

Parameter Details

Members
clientToken
Type: string

A unique, case-sensitive identifier that you provide to ensure the idempotency of the request. If you don’t specify a client token, the Amazon Web Services SDK automatically generates a client token and uses it for the request to ensure idempotency. The API will return idempotent responses for the last 10 client tokens used to successfully redrive the execution. These client tokens are valid for up to 15 minutes after they are first used.

executionArn
Required: Yes
Type: string

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

Result Syntax

[
    'redriveDate' => <DateTime>,
]

Result Details

Members
redriveDate
Required: Yes
Type: timestamp (string|DateTime or anything parsable by strtotime)

The date the execution was last redriven.

Errors

ExecutionDoesNotExist:

The specified execution does not exist.

ExecutionNotRedrivable:

The execution Amazon Resource Name (ARN) that you specified for executionArn cannot be redriven.

ExecutionLimitExceeded:

The maximum number of running executions has been reached. Running executions must end or be stopped before a new execution can be started.

InvalidArn:

The provided Amazon Resource Name (ARN) is not valid.

ValidationException:

The input does not satisfy the constraints specified by an Amazon Web Services service.

SendTaskFailure

$result = $client->sendTaskFailure([/* ... */]);
$promise = $client->sendTaskFailureAsync([/* ... */]);

Used by activity workers, Task states using the callback pattern, and optionally Task states using the job run pattern to report that the task identified by the taskToken failed.

For an execution with encryption enabled, Step Functions will encrypt the error and cause fields using the KMS key for the execution role.

A caller can mark a task as fail without using any KMS permissions in the execution role if the caller provides a null value for both error and cause fields because no data needs to be encrypted.

Parameter Syntax

$result = $client->sendTaskFailure([
    'cause' => '<string>',
    'error' => '<string>',
    'taskToken' => '<string>', // REQUIRED
]);

Parameter Details

Members
cause
Type: string

A more detailed explanation of the cause of the failure.

error
Type: string

The error code of the failure.

taskToken
Required: Yes
Type: string

The token that represents this task. Task tokens are generated by Step Functions when tasks are assigned to a worker, or in the context object when a workflow enters a task state. See GetActivityTaskOutput$taskToken.

Result Syntax

[]

Result Details

The results for this operation are always empty.

Errors

TaskDoesNotExist:

The activity does not exist.

InvalidToken:

The provided token is not valid.

TaskTimedOut:

The task token has either expired or the task associated with the token has already been closed.

KmsAccessDeniedException:

Either your KMS key policy or API caller does not have the required permissions.

KmsInvalidStateException:

The KMS key is not in valid state, for example: Disabled or Deleted.

KmsThrottlingException:

Received when KMS returns ThrottlingException for a KMS call that Step Functions makes on behalf of the caller.

SendTaskHeartbeat

$result = $client->sendTaskHeartbeat([/* ... */]);
$promise = $client->sendTaskHeartbeatAsync([/* ... */]);

Used by activity workers and Task states using the callback pattern, and optionally Task states using the job run pattern to report to Step Functions that the task represented by the specified taskToken is still making progress. This action resets the Heartbeat clock. The Heartbeat threshold is specified in the state machine's Amazon States Language definition (HeartbeatSeconds). This action does not in itself create an event in the execution history. However, if the task times out, the execution history contains an ActivityTimedOut entry for activities, or a TaskTimedOut entry for tasks using the job run or callback pattern.

The Timeout of a task, defined in the state machine's Amazon States Language definition, is its maximum allowed duration, regardless of the number of SendTaskHeartbeat requests received. Use HeartbeatSeconds to configure the timeout interval for heartbeats.

Parameter Syntax

$result = $client->sendTaskHeartbeat([
    'taskToken' => '<string>', // REQUIRED
]);

Parameter Details

Members
taskToken
Required: Yes
Type: string

The token that represents this task. Task tokens are generated by Step Functions when tasks are assigned to a worker, or in the context object when a workflow enters a task state. See GetActivityTaskOutput$taskToken.

Result Syntax

[]

Result Details

The results for this operation are always empty.

Errors

TaskDoesNotExist:

The activity does not exist.

InvalidToken:

The provided token is not valid.

TaskTimedOut:

The task token has either expired or the task associated with the token has already been closed.

SendTaskSuccess

$result = $client->sendTaskSuccess([/* ... */]);
$promise = $client->sendTaskSuccessAsync([/* ... */]);

Used by activity workers, Task states using the callback pattern, and optionally Task states using the job run pattern to report that the task identified by the taskToken completed successfully.

Parameter Syntax

$result = $client->sendTaskSuccess([
    'output' => '<string>', // REQUIRED
    'taskToken' => '<string>', // REQUIRED
]);

Parameter Details

Members
output
Required: Yes
Type: string

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

taskToken
Required: Yes
Type: string

The token that represents this task. Task tokens are generated by Step Functions when tasks are assigned to a worker, or in the context object when a workflow enters a task state. See GetActivityTaskOutput$taskToken.

Result Syntax

[]

Result Details

The results for this operation are always empty.

Errors

TaskDoesNotExist:

The activity does not exist.

InvalidOutput:

The provided JSON output data is not valid.

InvalidToken:

The provided token is not valid.

TaskTimedOut:

The task token has either expired or the task associated with the token has already been closed.

KmsAccessDeniedException:

Either your KMS key policy or API caller does not have the required permissions.

KmsInvalidStateException:

The KMS key is not in valid state, for example: Disabled or Deleted.

KmsThrottlingException:

Received when KMS returns ThrottlingException for a KMS call that Step Functions makes on behalf of the caller.

StartExecution

$result = $client->startExecution([/* ... */]);
$promise = $client->startExecutionAsync([/* ... */]);

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

    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>

    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, call StartExecution and provide the version ARN or the ARN of an alias that points to the version.

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.

Parameter Syntax

$result = $client->startExecution([
    'input' => '<string>',
    'name' => '<string>',
    'stateMachineArn' => '<string>', // REQUIRED
    'traceHeader' => '<string>',
]);

Parameter Details

Members
input
Type: string

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

"input": "{\"first_name\" : \"test\"}"

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

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

name
Type: string

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 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)

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

stateMachineArn
Required: Yes
Type: string

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.

traceHeader
Type: string

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

Result Syntax

[
    'executionArn' => '<string>',
    'startDate' => <DateTime>,
]

Result Details

Members
executionArn
Required: Yes
Type: string

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

startDate
Required: Yes
Type: timestamp (string|DateTime or anything parsable by strtotime)

The date the execution is started.

Errors

ExecutionLimitExceeded:

The maximum number of running executions has been reached. Running executions must end or be stopped before a new execution can be started.

ExecutionAlreadyExists:

The execution has the same name as another execution (but a different input).

Executions with the same name and input are considered idempotent.

InvalidArn:

The provided Amazon Resource Name (ARN) is not valid.

InvalidExecutionInput:

The provided JSON input data is not valid.

InvalidName:

The provided name is not valid.

StateMachineDoesNotExist:

The specified state machine does not exist.

StateMachineDeleting:

The specified state machine is being deleted.

ValidationException:

The input does not satisfy the constraints specified by an Amazon Web Services service.

KmsAccessDeniedException:

Either your KMS key policy or API caller does not have the required permissions.

KmsInvalidStateException:

The KMS key is not in valid state, for example: Disabled or Deleted.

KmsThrottlingException:

Received when KMS returns ThrottlingException for a KMS call that Step Functions makes on behalf of the caller.

StartSyncExecution

$result = $client->startSyncExecution([/* ... */]);
$promise = $client->startSyncExecutionAsync([/* ... */]);

Starts a Synchronous Express state machine execution. StartSyncExecution is not available for STANDARD workflows.

StartSyncExecution will return a 200 OK response, even if your execution fails, because the status code in the API response doesn't reflect function errors. Error codes are reserved for errors that prevent your execution from running, such as permissions errors, limit errors, or issues with your state machine code and configuration.

This API action isn't logged in CloudTrail.

Parameter Syntax

$result = $client->startSyncExecution([
    'includedData' => 'ALL_DATA|METADATA_ONLY',
    'input' => '<string>',
    'name' => '<string>',
    'stateMachineArn' => '<string>', // REQUIRED
    'traceHeader' => '<string>',
]);

Parameter Details

Members
includedData
Type: string

If your state machine definition is encrypted with a KMS key, callers must have kms:Decrypt permission to decrypt the definition. Alternatively, you can call the API with includedData = METADATA_ONLY to get a successful response without the encrypted definition.

input
Type: string

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

"input": "{\"first_name\" : \"test\"}"

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

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

name
Type: string

The name of the execution.

stateMachineArn
Required: Yes
Type: string

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

traceHeader
Type: string

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

Result Syntax

[
    'billingDetails' => [
        'billedDurationInMilliseconds' => <integer>,
        'billedMemoryUsedInMB' => <integer>,
    ],
    'cause' => '<string>',
    'error' => '<string>',
    'executionArn' => '<string>',
    'input' => '<string>',
    'inputDetails' => [
        'included' => true || false,
    ],
    'name' => '<string>',
    'output' => '<string>',
    'outputDetails' => [
        'included' => true || false,
    ],
    'startDate' => <DateTime>,
    'stateMachineArn' => '<string>',
    'status' => 'SUCCEEDED|FAILED|TIMED_OUT',
    'stopDate' => <DateTime>,
    'traceHeader' => '<string>',
]

Result Details

Members
billingDetails
Type: BillingDetails structure

An object that describes workflow billing details, including billed duration and memory use.

cause
Type: string

A more detailed explanation of the cause of the failure.

error
Type: string

The error code of the failure.

executionArn
Required: Yes
Type: string

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

input
Type: 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

Provides details about execution input or output.

name
Type: string

The name of the execution.

output
Type: string

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

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

outputDetails

Provides details about execution input or output.

startDate
Required: Yes
Type: timestamp (string|DateTime or anything parsable by strtotime)

The date the execution is started.

stateMachineArn
Type: string

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

status
Required: Yes
Type: string

The current status of the execution.

stopDate
Required: Yes
Type: timestamp (string|DateTime or anything parsable by strtotime)

If the execution has already ended, the date the execution stopped.

traceHeader
Type: string

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

Errors

InvalidArn:

The provided Amazon Resource Name (ARN) is not valid.

InvalidExecutionInput:

The provided JSON input data is not valid.

InvalidName:

The provided name is not valid.

StateMachineDoesNotExist:

The specified state machine does not exist.

StateMachineDeleting:

The specified state machine is being deleted.

StateMachineTypeNotSupported:

State machine type is not supported.

KmsAccessDeniedException:

Either your KMS key policy or API caller does not have the required permissions.

KmsInvalidStateException:

The KMS key is not in valid state, for example: Disabled or Deleted.

KmsThrottlingException:

Received when KMS returns ThrottlingException for a KMS call that Step Functions makes on behalf of the caller.

StopExecution

$result = $client->stopExecution([/* ... */]);
$promise = $client->stopExecutionAsync([/* ... */]);

Stops an execution.

This API action is not supported by EXPRESS state machines.

For an execution with encryption enabled, Step Functions will encrypt the error and cause fields using the KMS key for the execution role.

A caller can stop an execution without using any KMS permissions in the execution role if the caller provides a null value for both error and cause fields because no data needs to be encrypted.

Parameter Syntax

$result = $client->stopExecution([
    'cause' => '<string>',
    'error' => '<string>',
    'executionArn' => '<string>', // REQUIRED
]);

Parameter Details

Members
cause
Type: string

A more detailed explanation of the cause of the failure.

error
Type: string

The error code of the failure.

executionArn
Required: Yes
Type: string

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

Result Syntax

[
    'stopDate' => <DateTime>,
]

Result Details

Members
stopDate
Required: Yes
Type: timestamp (string|DateTime or anything parsable by strtotime)

The date the execution is stopped.

Errors

ExecutionDoesNotExist:

The specified execution does not exist.

InvalidArn:

The provided Amazon Resource Name (ARN) is not valid.

ValidationException:

The input does not satisfy the constraints specified by an Amazon Web Services service.

KmsAccessDeniedException:

Either your KMS key policy or API caller does not have the required permissions.

KmsInvalidStateException:

The KMS key is not in valid state, for example: Disabled or Deleted.

KmsThrottlingException:

Received when KMS returns ThrottlingException for a KMS call that Step Functions makes on behalf of the caller.

TagResource

$result = $client->tagResource([/* ... */]);
$promise = $client->tagResourceAsync([/* ... */]);

Add a tag to a Step Functions resource.

An array of key-value pairs. For more information, see Using Cost Allocation Tags in the Amazon Web Services Billing and Cost Management User Guide, and Controlling Access Using IAM Tags.

Tags may only contain Unicode letters, digits, white space, or these symbols: _ . : / = + - @.

Parameter Syntax

$result = $client->tagResource([
    'resourceArn' => '<string>', // REQUIRED
    'tags' => [ // REQUIRED
        [
            'key' => '<string>',
            'value' => '<string>',
        ],
        // ...
    ],
]);

Parameter Details

Members
resourceArn
Required: Yes
Type: string

The Amazon Resource Name (ARN) for the Step Functions state machine or activity.

tags
Required: Yes
Type: Array of Tag structures

The list of tags to add to a resource.

Tags may only contain Unicode letters, digits, white space, or these symbols: _ . : / = + - @.

Result Syntax

[]

Result Details

The results for this operation are always empty.

Errors

InvalidArn:

The provided Amazon Resource Name (ARN) is not valid.

ResourceNotFound:

Could not find the referenced resource.

TooManyTags:

You've exceeded the number of tags allowed for a resource. See the Limits Topic in the Step Functions Developer Guide.

TestState

$result = $client->testState([/* ... */]);
$promise = $client->testStateAsync([/* ... */]);

Accepts the definition of a single state and executes it. You can test a state without creating a state machine or updating an existing state machine. Using this API, you can test the following:

You can call this API on only one state at a time. The states that you can test include the following:

The TestState API assumes an IAM role which must contain the required IAM permissions for the resources your state is accessing. For information about the permissions a state might need, see IAM permissions to test a state.

The TestState API can run for up to five minutes. If the execution of a state exceeds this duration, it fails with the States.Timeout error.

TestState doesn't support Activity tasks, .sync or .waitForTaskToken service integration patterns, Parallel, or Map states.

Parameter Syntax

$result = $client->testState([
    'definition' => '<string>', // REQUIRED
    'input' => '<string>',
    'inspectionLevel' => 'INFO|DEBUG|TRACE',
    'revealSecrets' => true || false,
    'roleArn' => '<string>', // REQUIRED
]);

Parameter Details

Members
definition
Required: Yes
Type: string

The Amazon States Language (ASL) definition of the state.

input
Type: string

A string that contains the JSON input data for the state.

inspectionLevel
Type: string

Determines the values to return when a state is tested. You can specify one of the following types:

  • INFO: Shows the final state output. By default, Step Functions sets inspectionLevel to INFO if you don't specify a level.

  • DEBUG: Shows the final state output along with the input and output data processing result.

  • TRACE: Shows the HTTP request and response for an HTTP Task. This level also shows the final state output along with the input and output data processing result.

Each of these levels also provide information about the status of the state execution and the next state to transition to.

revealSecrets
Type: boolean

Specifies whether or not to include secret information in the test result. For HTTP Tasks, a secret includes the data that an EventBridge connection adds to modify the HTTP request headers, query parameters, and body. Step Functions doesn't omit any information included in the state definition or the HTTP response.

If you set revealSecrets to true, you must make sure that the IAM user that calls the TestState API has permission for the states:RevealSecrets action. For an example of IAM policy that sets the states:RevealSecrets permission, see IAM permissions to test a state. Without this permission, Step Functions throws an access denied error.

By default, revealSecrets is set to false.

roleArn
Required: Yes
Type: string

The Amazon Resource Name (ARN) of the execution role with the required IAM permissions for the state.

Result Syntax

[
    'cause' => '<string>',
    'error' => '<string>',
    'inspectionData' => [
        'afterInputPath' => '<string>',
        'afterParameters' => '<string>',
        'afterResultPath' => '<string>',
        'afterResultSelector' => '<string>',
        'input' => '<string>',
        'request' => [
            'body' => '<string>',
            'headers' => '<string>',
            'method' => '<string>',
            'protocol' => '<string>',
            'url' => '<string>',
        ],
        'response' => [
            'body' => '<string>',
            'headers' => '<string>',
            'protocol' => '<string>',
            'statusCode' => '<string>',
            'statusMessage' => '<string>',
        ],
        'result' => '<string>',
    ],
    'nextState' => '<string>',
    'output' => '<string>',
    'status' => 'SUCCEEDED|FAILED|RETRIABLE|CAUGHT_ERROR',
]

Result Details

Members
cause
Type: string

A detailed explanation of the cause for the error when the execution of a state fails.

error
Type: string

The error returned when the execution of a state fails.

inspectionData
Type: InspectionData structure

Returns additional details about the state's execution, including its input and output data processing flow, and HTTP request and response information. The inspectionLevel request parameter specifies which details are returned.

nextState
Type: string

The name of the next state to transition to. If you haven't defined a next state in your definition or if the execution of the state fails, this field doesn't contain a value.

output
Type: string

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

status
Type: string

The execution status of the state.

Errors

InvalidArn:

The provided Amazon Resource Name (ARN) is not valid.

InvalidDefinition:

The provided Amazon States Language definition is not valid.

InvalidExecutionInput:

The provided JSON input data is not valid.

ValidationException:

The input does not satisfy the constraints specified by an Amazon Web Services service.

UntagResource

$result = $client->untagResource([/* ... */]);
$promise = $client->untagResourceAsync([/* ... */]);

Remove a tag from a Step Functions resource

Parameter Syntax

$result = $client->untagResource([
    'resourceArn' => '<string>', // REQUIRED
    'tagKeys' => ['<string>', ...], // REQUIRED
]);

Parameter Details

Members
resourceArn
Required: Yes
Type: string

The Amazon Resource Name (ARN) for the Step Functions state machine or activity.

tagKeys
Required: Yes
Type: Array of strings

The list of tags to remove from the resource.

Result Syntax

[]

Result Details

The results for this operation are always empty.

Errors

InvalidArn:

The provided Amazon Resource Name (ARN) is not valid.

ResourceNotFound:

Could not find the referenced resource.

UpdateMapRun

$result = $client->updateMapRun([/* ... */]);
$promise = $client->updateMapRunAsync([/* ... */]);

Updates an in-progress Map Run's configuration to include changes to the settings that control maximum concurrency and Map Run failure.

Parameter Syntax

$result = $client->updateMapRun([
    'mapRunArn' => '<string>', // REQUIRED
    'maxConcurrency' => <integer>,
    'toleratedFailureCount' => <integer>,
    'toleratedFailurePercentage' => <float>,
]);

Parameter Details

Members
mapRunArn
Required: Yes
Type: string

The Amazon Resource Name (ARN) of a Map Run.

maxConcurrency
Type: int

The maximum number of child workflow executions that can be specified to run in parallel for the Map Run at the same time.

toleratedFailureCount
Type: long (int|float)

The maximum number of failed items before the Map Run fails.

toleratedFailurePercentage
Type: float

The maximum percentage of failed items before the Map Run fails.

Result Syntax

[]

Result Details

The results for this operation are always empty.

Errors

ResourceNotFound:

Could not find the referenced resource.

InvalidArn:

The provided Amazon Resource Name (ARN) is not valid.

ValidationException:

The input does not satisfy the constraints specified by an Amazon Web Services service.

UpdateStateMachine

$result = $client->updateStateMachine([/* ... */]);
$promise = $client->updateStateMachineAsync([/* ... */]);

Updates an existing state machine by modifying its definition, roleArn, loggingConfiguration, or EncryptionConfiguration. Running executions will continue to use the previous definition and roleArn. You must include at least one of definition or roleArn or you will receive a MissingRequiredParameter error.

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.

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

    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>

    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>

After you update your state machine, you can set the publish parameter to true in the same action to publish a new version. This way, you can opt-in to strict versioning of your state machine.

Step Functions assigns monotonically increasing integers for state machine versions, starting at version number 1.

All StartExecution calls within a few seconds use the updated definition and roleArn. Executions started immediately after you call UpdateStateMachine may use the previous state machine definition and roleArn.

Parameter Syntax

$result = $client->updateStateMachine([
    'definition' => '<string>',
    'encryptionConfiguration' => [
        'kmsDataKeyReusePeriodSeconds' => <integer>,
        'kmsKeyId' => '<string>',
        'type' => 'AWS_OWNED_KEY|CUSTOMER_MANAGED_KMS_KEY', // REQUIRED
    ],
    'loggingConfiguration' => [
        'destinations' => [
            [
                'cloudWatchLogsLogGroup' => [
                    'logGroupArn' => '<string>',
                ],
            ],
            // ...
        ],
        'includeExecutionData' => true || false,
        'level' => 'ALL|ERROR|FATAL|OFF',
    ],
    'publish' => true || false,
    'roleArn' => '<string>',
    'stateMachineArn' => '<string>', // REQUIRED
    'tracingConfiguration' => [
        'enabled' => true || false,
    ],
    'versionDescription' => '<string>',
]);

Parameter Details

Members
definition
Type: string

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

encryptionConfiguration
Type: EncryptionConfiguration structure

Settings to configure server-side encryption.

loggingConfiguration
Type: LoggingConfiguration structure

Use the LoggingConfiguration data type to set CloudWatch Logs options.

publish
Type: boolean

Specifies whether the state machine version is published. The default is false. To publish a version after updating the state machine, set publish to true.

roleArn
Type: string

The Amazon Resource Name (ARN) of the IAM role of the state machine.

stateMachineArn
Required: Yes
Type: string

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

tracingConfiguration
Type: TracingConfiguration structure

Selects whether X-Ray tracing is enabled.

versionDescription
Type: string

An optional description of the state machine version to publish.

You can only specify the versionDescription parameter if you've set publish to true.

Result Syntax

[
    'revisionId' => '<string>',
    'stateMachineVersionArn' => '<string>',
    'updateDate' => <DateTime>,
]

Result Details

Members
revisionId
Type: string

The revision identifier for the updated state machine.

stateMachineVersionArn
Type: string

The Amazon Resource Name (ARN) of the published state machine version.

If the publish parameter isn't set to true, this field returns null.

updateDate
Required: Yes
Type: timestamp (string|DateTime or anything parsable by strtotime)

The date and time the state machine was updated.

Errors

InvalidArn:

The provided Amazon Resource Name (ARN) is not valid.

InvalidDefinition:

The provided Amazon States Language definition is not valid.

InvalidLoggingConfiguration:

Configuration is not valid.

InvalidTracingConfiguration:

Your tracingConfiguration key does not match, or enabled has not been set to true or false.

MissingRequiredParameter:

Request is missing a required parameter. This error occurs if both definition and roleArn are not specified.

StateMachineDeleting:

The specified state machine is being deleted.

StateMachineDoesNotExist:

The specified state machine does not exist.

ServiceQuotaExceededException:

The request would cause a service quota to be exceeded.

HTTP Status Code: 402

ConflictException:

Updating or deleting a resource can cause an inconsistent state. This error occurs when there're concurrent requests for DeleteStateMachineVersion, PublishStateMachineVersion, or UpdateStateMachine with the publish parameter set to true.

HTTP Status Code: 409

ValidationException:

The input does not satisfy the constraints specified by an Amazon Web Services service.

InvalidEncryptionConfiguration:

Received when encryptionConfiguration is specified but various conditions exist which make the configuration invalid. For example, if type is set to CUSTOMER_MANAGED_KMS_KEY, but kmsKeyId is null, or kmsDataKeyReusePeriodSeconds is not between 60 and 900, or the KMS key is not symmetric or inactive.

KmsAccessDeniedException:

Either your KMS key policy or API caller does not have the required permissions.

KmsThrottlingException:

Received when KMS returns ThrottlingException for a KMS call that Step Functions makes on behalf of the caller.

UpdateStateMachineAlias

$result = $client->updateStateMachineAlias([/* ... */]);
$promise = $client->updateStateMachineAliasAsync([/* ... */]);

Updates the configuration of an existing state machine alias by modifying its description or routingConfiguration.

You must specify at least one of the description or routingConfiguration parameters to update a state machine alias.

UpdateStateMachineAlias is an idempotent API. Step Functions bases the idempotency check on the stateMachineAliasArn, description, and routingConfiguration parameters. Requests with the same parameters return an idempotent response.

This operation is eventually consistent. All StartExecution requests made within a few seconds use the latest alias configuration. Executions started immediately after calling UpdateStateMachineAlias may use the previous routing configuration.

Related operations:

Parameter Syntax

$result = $client->updateStateMachineAlias([
    'description' => '<string>',
    'routingConfiguration' => [
        [
            'stateMachineVersionArn' => '<string>', // REQUIRED
            'weight' => <integer>, // REQUIRED
        ],
        // ...
    ],
    'stateMachineAliasArn' => '<string>', // REQUIRED
]);

Parameter Details

Members
description
Type: string

A description of the state machine alias.

routingConfiguration
Type: Array of RoutingConfigurationListItem structures

The routing configuration of the state machine alias.

An array of RoutingConfig objects that specifies up to two state machine versions that the alias starts executions for.

stateMachineAliasArn
Required: Yes
Type: string

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

Result Syntax

[
    'updateDate' => <DateTime>,
]

Result Details

Members
updateDate
Required: Yes
Type: timestamp (string|DateTime or anything parsable by strtotime)

The date and time the state machine alias was updated.

Errors

ValidationException:

The input does not satisfy the constraints specified by an Amazon Web Services service.

InvalidArn:

The provided Amazon Resource Name (ARN) is not valid.

ResourceNotFound:

Could not find the referenced resource.

ConflictException:

Updating or deleting a resource can cause an inconsistent state. This error occurs when there're concurrent requests for DeleteStateMachineVersion, PublishStateMachineVersion, or UpdateStateMachine with the publish parameter set to true.

HTTP Status Code: 409

StateMachineDeleting:

The specified state machine is being deleted.

ValidateStateMachineDefinition

$result = $client->validateStateMachineDefinition([/* ... */]);
$promise = $client->validateStateMachineDefinitionAsync([/* ... */]);

Validates the syntax of a state machine definition.

You can validate that a state machine definition is correct without creating a state machine resource. Step Functions will implicitly perform the same syntax check when you invoke CreateStateMachine and UpdateStateMachine. State machine definitions are specified using a JSON-based, structured language. For more information on Amazon States Language see Amazon States Language (ASL).

Suggested uses for ValidateStateMachineDefinition:

  • Integrate automated checks into your code review or Continuous Integration (CI) process to validate state machine definitions before starting deployments.

  • Run the validation from a Git pre-commit hook to check your state machine definitions before committing them to your source repository.

Errors found in the state machine definition will be returned in the response as a list of diagnostic elements, rather than raise an exception.

Parameter Syntax

$result = $client->validateStateMachineDefinition([
    'definition' => '<string>', // REQUIRED
    'maxResults' => <integer>,
    'severity' => 'ERROR|WARNING',
    'type' => 'STANDARD|EXPRESS',
]);

Parameter Details

Members
definition
Required: Yes
Type: string

The Amazon States Language definition of the state machine. For more information, see Amazon States Language (ASL).

maxResults
Type: int

The maximum number of diagnostics that are returned per call. The default and maximum value is 100. Setting the value to 0 will also use the default of 100.

If the number of diagnostics returned in the response exceeds maxResults, the value of the truncated field in the response will be set to true.

severity
Type: string

Minimum level of diagnostics to return. ERROR returns only ERROR diagnostics, whereas WARNING returns both WARNING and ERROR diagnostics. The default is ERROR.

type
Type: string

The target type of state machine for this definition. The default is STANDARD.

Result Syntax

[
    'diagnostics' => [
        [
            'code' => '<string>',
            'location' => '<string>',
            'message' => '<string>',
            'severity' => 'ERROR|WARNING',
        ],
        // ...
    ],
    'result' => 'OK|FAIL',
    'truncated' => true || false,
]

Result Details

Members
diagnostics
Required: Yes
Type: Array of ValidateStateMachineDefinitionDiagnostic structures

If the result is OK, this field will be empty. When there are errors, this field will contain an array of Diagnostic objects to help you troubleshoot.

result
Required: Yes
Type: string

The result value will be OK when no syntax errors are found, or FAIL if the workflow definition does not pass verification.

truncated
Type: boolean

The result value will be true if the number of diagnostics found in the workflow definition exceeds maxResults. When all diagnostics results are returned, the value will be false.

Errors

ValidationException:

The input does not satisfy the constraints specified by an Amazon Web Services service.

Shapes

ActivityAlreadyExists

Description

Activity already exists. EncryptionConfiguration may not be updated.

Members
message
Type: string

ActivityDoesNotExist

Description

The specified activity does not exist.

Members
message
Type: string

ActivityFailedEventDetails

Description

Contains details about an activity that failed during an execution.

Members
cause
Type: string

A more detailed explanation of the cause of the failure.

error
Type: string

The error code of the failure.

ActivityLimitExceeded

Description

The maximum number of activities has been reached. Existing activities must be deleted before a new activity can be created.

Members
message
Type: string

ActivityListItem

Description

Contains details about an activity.

Members
activityArn
Required: Yes
Type: string

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

creationDate
Required: Yes
Type: timestamp (string|DateTime or anything parsable by strtotime)

The date the activity is created.

name
Required: Yes
Type: string

The name of the activity.

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

ActivityScheduleFailedEventDetails

Description

Contains details about an activity schedule failure that occurred during an execution.

Members
cause
Type: string

A more detailed explanation of the cause of the failure.

error
Type: string

The error code of the failure.

ActivityScheduledEventDetails

Description

Contains details about an activity scheduled during an execution.

Members
heartbeatInSeconds
Type: long (int|float)

The maximum allowed duration between two heartbeats for the activity task.

input
Type: string

The JSON data input to the activity task. Length constraints apply to the payload size, and are expressed as bytes in UTF-8 encoding.

inputDetails

Contains details about the input for an execution history event.

resource
Required: Yes
Type: string

The Amazon Resource Name (ARN) of the scheduled activity.

timeoutInSeconds
Type: long (int|float)

The maximum allowed duration of the activity task.

ActivityStartedEventDetails

Description

Contains details about the start of an activity during an execution.

Members
workerName
Type: string

The name of the worker that the task is assigned to. These names are provided by the workers when calling GetActivityTask.

ActivitySucceededEventDetails

Description

Contains details about an activity that successfully terminated during an execution.

Members
output
Type: string

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

outputDetails

Contains details about the output of an execution history event.

ActivityTimedOutEventDetails

Description

Contains details about an activity timeout that occurred during an execution.

Members
cause
Type: string

A more detailed explanation of the cause of the timeout.

error
Type: string

The error code of the failure.

ActivityWorkerLimitExceeded

Description

The maximum number of workers concurrently polling for activity tasks has been reached.

Members
message
Type: string

BillingDetails

Description

An object that describes workflow billing details.

Members
billedDurationInMilliseconds
Type: long (int|float)

Billed duration of your workflow, in milliseconds.

billedMemoryUsedInMB
Type: long (int|float)

Billed memory consumption of your workflow, in MB.

CloudWatchEventsExecutionDataDetails

Description

Provides details about execution input or output.

Members
included
Type: boolean

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

CloudWatchLogsLogGroup

Description

Members
logGroupArn
Type: string

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

EncryptionConfiguration

Description

Settings to configure server-side encryption.

For additional control over security, you can encrypt your data using a customer-managed key for Step Functions state machines and activities. You can configure a symmetric KMS key and data key reuse period when creating or updating a State Machine, and when creating an Activity. The execution history and state machine definition will be encrypted with the key applied to the State Machine. Activity inputs will be encrypted with the key applied to the Activity.

Step Functions automatically enables encryption at rest using Amazon Web Services owned keys at no charge. However, KMS charges apply when using a customer managed key. For more information about pricing, see Key Management Service pricing.

For more information on KMS, see What is Key Management Service?

Members
kmsDataKeyReusePeriodSeconds
Type: int

Maximum duration that Step Functions will reuse data keys. When the period expires, Step Functions will call GenerateDataKey. Only applies to customer managed keys.

kmsKeyId
Type: string

An alias, alias ARN, key ID, or key ARN of a symmetric encryption KMS key to encrypt data. To specify a KMS key in a different Amazon Web Services account, you must use the key ARN or alias ARN.

type
Required: Yes
Type: string

Encryption type

ExecutionAbortedEventDetails

Description

Contains details about an abort of an execution.

Members
cause
Type: string

A more detailed explanation of the cause of the failure.

error
Type: string

The error code of the failure.

ExecutionAlreadyExists

Description

The execution has the same name as another execution (but a different input).

Executions with the same name and input are considered idempotent.

Members
message
Type: string

ExecutionDoesNotExist

Description

The specified execution does not exist.

Members
message
Type: string

ExecutionFailedEventDetails

Description

Contains details about an execution failure event.

Members
cause
Type: string

A more detailed explanation of the cause of the failure.

error
Type: string

The error code of the failure.

ExecutionLimitExceeded

Description

The maximum number of running executions has been reached. Running executions must end or be stopped before a new execution can be started.

Members
message
Type: string

ExecutionListItem

Description

Contains details about an execution.

Members
executionArn
Required: Yes
Type: string

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

itemCount
Type: int

The total number of items processed in a child workflow execution. This field is returned only if mapRunArn was specified in the ListExecutions API action. If stateMachineArn was specified in ListExecutions, the itemCount field isn't returned.

mapRunArn
Type: string

The Amazon Resource Name (ARN) of a Map Run. This field is returned only if mapRunArn was specified in the ListExecutions API action. If stateMachineArn was specified in ListExecutions, the mapRunArn isn't returned.

name
Required: Yes
Type: 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 _.

redriveCount
Type: int

The number of times you've redriven an execution. If you have not yet redriven an execution, the redriveCount is 0. This count is only updated when you successfully redrive an execution.

redriveDate
Type: timestamp (string|DateTime or anything parsable by strtotime)

The date the execution was last redriven.

startDate
Required: Yes
Type: timestamp (string|DateTime or anything parsable by strtotime)

The date the execution started.

stateMachineAliasArn
Type: string

The Amazon Resource Name (ARN) of the state machine alias used to start an execution.

If the state machine execution was started with an unqualified ARN or a version ARN, it returns null.

stateMachineArn
Required: Yes
Type: string

The Amazon Resource Name (ARN) of the state machine that ran the execution.

stateMachineVersionArn
Type: string

The Amazon Resource Name (ARN) of the state machine version associated with the execution.

If the state machine execution was started with an unqualified ARN, it returns null.

If the execution was started using a stateMachineAliasArn, both the stateMachineAliasArn and stateMachineVersionArn parameters contain the respective values.

status
Required: Yes
Type: string

The current status of the execution.

stopDate
Type: timestamp (string|DateTime or anything parsable by strtotime)

If the execution already ended, the date the execution stopped.

ExecutionNotRedrivable

Description

The execution Amazon Resource Name (ARN) that you specified for executionArn cannot be redriven.

Members
message
Type: string

ExecutionRedrivenEventDetails

Description

Contains details about a redriven execution.

Members
redriveCount
Type: int

The number of times you've redriven an execution. If you have not yet redriven an execution, the redriveCount is 0. This count is not updated for redrives that failed to start or are pending to be redriven.

ExecutionStartedEventDetails

Description

Contains details about the start of the execution.

Members
input
Type: string

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

inputDetails

Contains details about the input for an execution history event.

roleArn
Type: string

The Amazon Resource Name (ARN) of the IAM role used for executing Lambda tasks.

stateMachineAliasArn
Type: string

The Amazon Resource Name (ARN) that identifies a state machine alias used for starting the state machine execution.

stateMachineVersionArn
Type: string

The Amazon Resource Name (ARN) that identifies a state machine version used for starting the state machine execution.

ExecutionSucceededEventDetails

Description

Contains details about the successful termination of the execution.

Members
output
Type: string

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

outputDetails

Contains details about the output of an execution history event.

ExecutionTimedOutEventDetails

Description

Contains details about the execution timeout that occurred during the execution.

Members
cause
Type: string

A more detailed explanation of the cause of the timeout.

error
Type: string

The error code of the failure.

HistoryEvent

Description

Contains details about the events of an execution.

Members
activityFailedEventDetails
Type: ActivityFailedEventDetails structure

Contains details about an activity that failed during an execution.

activityScheduleFailedEventDetails

Contains details about an activity schedule event that failed during an execution.

activityScheduledEventDetails

Contains details about an activity scheduled during an execution.

activityStartedEventDetails
Type: ActivityStartedEventDetails structure

Contains details about the start of an activity during an execution.

activitySucceededEventDetails

Contains details about an activity that successfully terminated during an execution.

activityTimedOutEventDetails

Contains details about an activity timeout that occurred during an execution.

executionAbortedEventDetails

Contains details about an abort of an execution.

executionFailedEventDetails
Type: ExecutionFailedEventDetails structure

Contains details about an execution failure event.

executionRedrivenEventDetails

Contains details about the redrive attempt of an execution.

executionStartedEventDetails

Contains details about the start of the execution.

executionSucceededEventDetails

Contains details about the successful termination of the execution.

executionTimedOutEventDetails

Contains details about the execution timeout that occurred during the execution.

id
Required: Yes
Type: long (int|float)

The id of the event. Events are numbered sequentially, starting at one.

lambdaFunctionFailedEventDetails

Contains details about a Lambda function that failed during an execution.

lambdaFunctionScheduleFailedEventDetails

Contains details about a failed Lambda function schedule event that occurred during an execution.

lambdaFunctionScheduledEventDetails

Contains details about a Lambda function scheduled during an execution.

lambdaFunctionStartFailedEventDetails

Contains details about a lambda function that failed to start during an execution.

lambdaFunctionSucceededEventDetails

Contains details about a Lambda function that terminated successfully during an execution.

lambdaFunctionTimedOutEventDetails

Contains details about a Lambda function timeout that occurred during an execution.

mapIterationAbortedEventDetails
Type: MapIterationEventDetails structure

Contains details about an iteration of a Map state that was aborted.

mapIterationFailedEventDetails
Type: MapIterationEventDetails structure

Contains details about an iteration of a Map state that failed.

mapIterationStartedEventDetails
Type: MapIterationEventDetails structure

Contains details about an iteration of a Map state that was started.

mapIterationSucceededEventDetails
Type: MapIterationEventDetails structure

Contains details about an iteration of a Map state that succeeded.

mapRunFailedEventDetails
Type: MapRunFailedEventDetails structure

Contains error and cause details about a Map Run that failed.

mapRunRedrivenEventDetails
Type: MapRunRedrivenEventDetails structure

Contains details about the redrive attempt of a Map Run.

mapRunStartedEventDetails
Type: MapRunStartedEventDetails structure

Contains details, such as mapRunArn, and the start date and time of a Map Run. mapRunArn is the Amazon Resource Name (ARN) of the Map Run that was started.

mapStateStartedEventDetails
Type: MapStateStartedEventDetails structure

Contains details about Map state that was started.

previousEventId
Type: long (int|float)

The id of the previous event.

stateEnteredEventDetails
Type: StateEnteredEventDetails structure

Contains details about a state entered during an execution.

stateExitedEventDetails
Type: StateExitedEventDetails structure

Contains details about an exit from a state during an execution.

taskFailedEventDetails
Type: TaskFailedEventDetails structure

Contains details about the failure of a task.

taskScheduledEventDetails
Type: TaskScheduledEventDetails structure

Contains details about a task that was scheduled.

taskStartFailedEventDetails
Type: TaskStartFailedEventDetails structure

Contains details about a task that failed to start.

taskStartedEventDetails
Type: TaskStartedEventDetails structure

Contains details about a task that was started.

taskSubmitFailedEventDetails

Contains details about a task that where the submit failed.

taskSubmittedEventDetails
Type: TaskSubmittedEventDetails structure

Contains details about a submitted task.

taskSucceededEventDetails
Type: TaskSucceededEventDetails structure

Contains details about a task that succeeded.

taskTimedOutEventDetails
Type: TaskTimedOutEventDetails structure

Contains details about a task that timed out.

timestamp
Required: Yes
Type: timestamp (string|DateTime or anything parsable by strtotime)

The date and time the event occurred.

type
Required: Yes
Type: string

The type of the event.

HistoryEventExecutionDataDetails

Description

Provides details about input or output in an execution history event.

Members
truncated
Type: boolean

Indicates whether input or output was truncated in the response. Always false for API calls.

InspectionData

Description

Contains additional details about the state's execution, including its input and output data processing flow, and HTTP request and response information.

Members
afterInputPath
Type: string

The input after Step Functions applies the InputPath filter.

afterParameters
Type: string

The effective input after Step Functions applies the Parameters filter.

afterResultPath
Type: string

The effective result combined with the raw state input after Step Functions applies the ResultPath filter.

afterResultSelector
Type: string

The effective result after Step Functions applies the ResultSelector filter.

input
Type: string

The raw state input.

request
Type: InspectionDataRequest structure

The raw HTTP request that is sent when you test an HTTP Task.

response
Type: InspectionDataResponse structure

The raw HTTP response that is returned when you test an HTTP Task.

result
Type: string

The state's raw result.

InspectionDataRequest

Description

Contains additional details about the state's execution, including its input and output data processing flow, and HTTP request information.

Members
body
Type: string

The request body for the HTTP request.

headers
Type: string

The request headers associated with the HTTP request.

method
Type: string

The HTTP method used for the HTTP request.

protocol
Type: string

The protocol used to make the HTTP request.

url
Type: string

The API endpoint used for the HTTP request.

InspectionDataResponse

Description

Contains additional details about the state's execution, including its input and output data processing flow, and HTTP response information. The inspectionLevel request parameter specifies which details are returned.

Members
body
Type: string

The HTTP response returned.

headers
Type: string

The response headers associated with the HTTP response.

protocol
Type: string

The protocol used to return the HTTP response.

statusCode
Type: string

The HTTP response status code for the HTTP response.

statusMessage
Type: string

The message associated with the HTTP status code.

InvalidArn

Description

The provided Amazon Resource Name (ARN) is not valid.

Members
message
Type: string

InvalidDefinition

Description

The provided Amazon States Language definition is not valid.

Members
message
Type: string

InvalidEncryptionConfiguration

Description

Received when encryptionConfiguration is specified but various conditions exist which make the configuration invalid. For example, if type is set to CUSTOMER_MANAGED_KMS_KEY, but kmsKeyId is null, or kmsDataKeyReusePeriodSeconds is not between 60 and 900, or the KMS key is not symmetric or inactive.

Members
message
Type: string

InvalidExecutionInput

Description

The provided JSON input data is not valid.

Members
message
Type: string

InvalidLoggingConfiguration

Description

Configuration is not valid.

Members
message
Type: string

InvalidName

Description

The provided name is not valid.

Members
message
Type: string

InvalidOutput

Description

The provided JSON output data is not valid.

Members
message
Type: string

InvalidToken

Description

The provided token is not valid.

Members
message
Type: string

InvalidTracingConfiguration

Description

Your tracingConfiguration key does not match, or enabled has not been set to true or false.

Members
message
Type: string

KmsAccessDeniedException

Description

Either your KMS key policy or API caller does not have the required permissions.

Members
message
Type: string

KmsInvalidStateException

Description

The KMS key is not in valid state, for example: Disabled or Deleted.

Members
kmsKeyState
Type: string

Current status of the KMS; key. For example: DISABLED, PENDING_DELETION, PENDING_IMPORT, UNAVAILABLE, CREATING.

message
Type: string

KmsThrottlingException

Description

Received when KMS returns ThrottlingException for a KMS call that Step Functions makes on behalf of the caller.

Members
message
Type: string

LambdaFunctionFailedEventDetails

Description

Contains details about a Lambda function that failed during an execution.

Members
cause
Type: string

A more detailed explanation of the cause of the failure.

error
Type: string

The error code of the failure.

LambdaFunctionScheduleFailedEventDetails

Description

Contains details about a failed Lambda function schedule event that occurred during an execution.

Members
cause
Type: string

A more detailed explanation of the cause of the failure.

error
Type: string

The error code of the failure.

LambdaFunctionScheduledEventDetails

Description

Contains details about a Lambda function scheduled during an execution.

Members
input
Type: string

The JSON data input to the Lambda function. Length constraints apply to the payload size, and are expressed as bytes in UTF-8 encoding.

inputDetails

Contains details about input for an execution history event.

resource
Required: Yes
Type: string

The Amazon Resource Name (ARN) of the scheduled Lambda function.

taskCredentials
Type: TaskCredentials structure

The credentials that Step Functions uses for the task.

timeoutInSeconds
Type: long (int|float)

The maximum allowed duration of the Lambda function.

LambdaFunctionStartFailedEventDetails

Description

Contains details about a lambda function that failed to start during an execution.

Members
cause
Type: string

A more detailed explanation of the cause of the failure.

error
Type: string

The error code of the failure.

LambdaFunctionSucceededEventDetails

Description

Contains details about a Lambda function that successfully terminated during an execution.

Members
output
Type: string

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

outputDetails

Contains details about the output of an execution history event.

LambdaFunctionTimedOutEventDetails

Description

Contains details about a Lambda function timeout that occurred during an execution.

Members
cause
Type: string

A more detailed explanation of the cause of the timeout.

error
Type: string

The error code of the failure.

LogDestination

Description

Members
cloudWatchLogsLogGroup
Type: CloudWatchLogsLogGroup structure

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

LoggingConfiguration

Description

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

Members
destinations
Type: Array of LogDestination structures

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.

includeExecutionData
Type: boolean

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

level
Type: string

Defines which category of execution history events are logged.

MapIterationEventDetails

Description

Contains details about an iteration of a Map state.

Members
index
Type: int

The index of the array belonging to the Map state iteration.

name
Type: string

The name of the iteration’s parent Map state.

MapRunExecutionCounts

Description

Contains details about all of the child workflow executions started by a Map Run.

Members
aborted
Required: Yes
Type: long (int|float)

The total number of child workflow executions that were started by a Map Run and were running, but were either stopped by the user or by Step Functions because the Map Run failed.

failed
Required: Yes
Type: long (int|float)

The total number of child workflow executions that were started by a Map Run, but have failed.

failuresNotRedrivable
Type: long (int|float)

The number of FAILED, ABORTED, or TIMED_OUT child workflow executions that cannot be redriven because their execution status is terminal. For example, child workflows with an execution status of FAILED, ABORTED, or TIMED_OUT and a redriveStatus of NOT_REDRIVABLE.

pending
Required: Yes
Type: long (int|float)

The total number of child workflow executions that were started by a Map Run, but haven't started executing yet.

pendingRedrive
Type: long (int|float)

The number of unsuccessful child workflow executions currently waiting to be redriven. The status of these child workflow executions could be FAILED, ABORTED, or TIMED_OUT in the original execution attempt or a previous redrive attempt.

resultsWritten
Required: Yes
Type: long (int|float)

Returns the count of child workflow executions whose results were written by ResultWriter. For more information, see ResultWriter in the Step Functions Developer Guide.

running
Required: Yes
Type: long (int|float)

The total number of child workflow executions that were started by a Map Run and are currently in-progress.

succeeded
Required: Yes
Type: long (int|float)

The total number of child workflow executions that were started by a Map Run and have completed successfully.

timedOut
Required: Yes
Type: long (int|float)

The total number of child workflow executions that were started by a Map Run and have timed out.

total
Required: Yes
Type: long (int|float)

The total number of child workflow executions that were started by a Map Run.

MapRunFailedEventDetails

Description

Contains details about a Map Run failure event that occurred during a state machine execution.

Members
cause
Type: string

A more detailed explanation of the cause of the failure.

error
Type: string

The error code of the Map Run failure.

MapRunItemCounts

Description

Contains details about items that were processed in all of the child workflow executions that were started by a Map Run.

Members
aborted
Required: Yes
Type: long (int|float)

The total number of items processed in child workflow executions that were either stopped by the user or by Step Functions, because the Map Run failed.

failed
Required: Yes
Type: long (int|float)

The total number of items processed in child workflow executions that have failed.

failuresNotRedrivable
Type: long (int|float)

The number of FAILED, ABORTED, or TIMED_OUT items in child workflow executions that cannot be redriven because the execution status of those child workflows is terminal. For example, child workflows with an execution status of FAILED, ABORTED, or TIMED_OUT and a redriveStatus of NOT_REDRIVABLE.

pending
Required: Yes
Type: long (int|float)

The total number of items to process in child workflow executions that haven't started running yet.

pendingRedrive
Type: long (int|float)

The number of unsuccessful items in child workflow executions currently waiting to be redriven.

resultsWritten
Required: Yes
Type: long (int|float)

Returns the count of items whose results were written by ResultWriter. For more information, see ResultWriter in the Step Functions Developer Guide.

running
Required: Yes
Type: long (int|float)

The total number of items being processed in child workflow executions that are currently in-progress.

succeeded
Required: Yes
Type: long (int|float)

The total number of items processed in child workflow executions that have completed successfully.

timedOut
Required: Yes
Type: long (int|float)

The total number of items processed in child workflow executions that have timed out.

total
Required: Yes
Type: long (int|float)

The total number of items processed in all the child workflow executions started by a Map Run.

MapRunListItem

Description

Contains details about a specific Map Run.

Members
executionArn
Required: Yes
Type: string

The executionArn of the execution from which the Map Run was started.

mapRunArn
Required: Yes
Type: string

The Amazon Resource Name (ARN) of the Map Run.

startDate
Required: Yes
Type: timestamp (string|DateTime or anything parsable by strtotime)

The date on which the Map Run started.

stateMachineArn
Required: Yes
Type: string

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

stopDate
Type: timestamp (string|DateTime or anything parsable by strtotime)

The date on which the Map Run stopped.

MapRunRedrivenEventDetails

Description

Contains details about a Map Run that was redriven.

Members
mapRunArn
Type: string

The Amazon Resource Name (ARN) of a Map Run that was redriven.

redriveCount
Type: int

The number of times the Map Run has been redriven at this point in the execution's history including this event. The redrive count for a redriven Map Run is always greater than 0.

MapRunStartedEventDetails

Description

Contains details about a Map Run that was started during a state machine execution.

Members
mapRunArn
Type: string

The Amazon Resource Name (ARN) of a Map Run that was started.

MapStateStartedEventDetails

Description

Details about a Map state that was started.

Members
length
Type: int

The size of the array for Map state iterations.

MissingRequiredParameter

Description

Request is missing a required parameter. This error occurs if both definition and roleArn are not specified.

Members
message
Type: string

ResourceNotFound

Description

Could not find the referenced resource.

Members
message
Type: string
resourceName
Type: string

RoutingConfigurationListItem

Description

Contains details about the routing configuration of a state machine alias. In a routing configuration, you define an array of objects that specify up to two state machine versions. You also specify the percentage of traffic to be routed to each version.

Members
stateMachineVersionArn
Required: Yes
Type: string

The Amazon Resource Name (ARN) that identifies one or two state machine versions defined in the routing configuration.

If you specify the ARN of a second version, it must belong to the same state machine as the first version.

weight
Required: Yes
Type: int

The percentage of traffic you want to route to a state machine version. The sum of the weights in the routing configuration must be equal to 100.

ServiceQuotaExceededException

Description

The request would cause a service quota to be exceeded.

HTTP Status Code: 402

Members
message
Type: string

StateEnteredEventDetails

Description

Contains details about a state entered during an execution.

Members
input
Type: string

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

inputDetails

Contains details about the input for an execution history event.

name
Required: Yes
Type: string

The name of the state.

StateExitedEventDetails

Description

Contains details about an exit from a state during an execution.

Members
name
Required: Yes
Type: string

The name of the state.

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

output
Type: string

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

outputDetails

Contains details about the output of an execution history event.

StateMachineAliasListItem

Description

Contains details about a specific state machine alias.

Members
creationDate
Required: Yes
Type: timestamp (string|DateTime or anything parsable by strtotime)

The creation date of a state machine alias.

stateMachineAliasArn
Required: Yes
Type: string

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

StateMachineAlreadyExists

Description

A state machine with the same name but a different definition or role ARN already exists.

Members
message
Type: string

StateMachineDeleting

Description

The specified state machine is being deleted.

Members
message
Type: string

StateMachineDoesNotExist

Description

The specified state machine does not exist.

Members
message
Type: string

StateMachineLimitExceeded

Description

The maximum number of state machines has been reached. Existing state machines must be deleted before a new state machine can be created.

Members
message
Type: string

StateMachineListItem

Description

Contains details about the state machine.

Members
creationDate
Required: Yes
Type: timestamp (string|DateTime or anything parsable by strtotime)

The date the state machine is created.

name
Required: Yes
Type: 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 _.

stateMachineArn
Required: Yes
Type: string

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

type
Required: Yes
Type: string

StateMachineTypeNotSupported

Description

State machine type is not supported.

Members
message
Type: string

StateMachineVersionListItem

Description

Contains details about a specific state machine version.

Members
creationDate
Required: Yes
Type: timestamp (string|DateTime or anything parsable by strtotime)

The creation date of a state machine version.

stateMachineVersionArn
Required: Yes
Type: string

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

Tag

Description

Tags are key-value pairs that can be associated with Step Functions state machines and activities.

An array of key-value pairs. For more information, see Using Cost Allocation Tags in the Amazon Web Services Billing and Cost Management User Guide, and Controlling Access Using IAM Tags.

Tags may only contain Unicode letters, digits, white space, or these symbols: _ . : / = + - @.

Members
key
Type: string

The key of a tag.

value
Type: string

The value of a tag.

TaskCredentials

Description

Contains details about the credentials that Step Functions uses for a task.

Members
roleArn
Type: string

The ARN of an IAM role that Step Functions assumes for the task. The role can allow cross-account access to resources.

TaskDoesNotExist

Description

The activity does not exist.

Members
message
Type: string

TaskFailedEventDetails

Description

Contains details about a task failure event.

Members
cause
Type: string

A more detailed explanation of the cause of the failure.

error
Type: string

The error code of the failure.

resource
Required: Yes
Type: string

The action of the resource called by a task state.

resourceType
Required: Yes
Type: string

The service name of the resource in a task state.

TaskScheduledEventDetails

Description

Contains details about a task scheduled during an execution.

Members
heartbeatInSeconds
Type: long (int|float)

The maximum allowed duration between two heartbeats for the task.

parameters
Required: Yes
Type: string

The JSON data passed to the resource referenced in a task state. Length constraints apply to the payload size, and are expressed as bytes in UTF-8 encoding.

region
Required: Yes
Type: string

The region of the scheduled task

resource
Required: Yes
Type: string

The action of the resource called by a task state.

resourceType
Required: Yes
Type: string

The service name of the resource in a task state.

taskCredentials
Type: TaskCredentials structure

The credentials that Step Functions uses for the task.

timeoutInSeconds
Type: long (int|float)

The maximum allowed duration of the task.

TaskStartFailedEventDetails

Description

Contains details about a task that failed to start during an execution.

Members
cause
Type: string

A more detailed explanation of the cause of the failure.

error
Type: string

The error code of the failure.

resource
Required: Yes
Type: string

The action of the resource called by a task state.

resourceType
Required: Yes
Type: string

The service name of the resource in a task state.

TaskStartedEventDetails

Description

Contains details about the start of a task during an execution.

Members
resource
Required: Yes
Type: string

The action of the resource called by a task state.

resourceType
Required: Yes
Type: string

The service name of the resource in a task state.

TaskSubmitFailedEventDetails

Description

Contains details about a task that failed to submit during an execution.

Members
cause
Type: string

A more detailed explanation of the cause of the failure.

error
Type: string

The error code of the failure.

resource
Required: Yes
Type: string

The action of the resource called by a task state.

resourceType
Required: Yes
Type: string

The service name of the resource in a task state.

TaskSubmittedEventDetails

Description

Contains details about a task submitted to a resource .

Members
output
Type: string

The response from a resource when a task has started. Length constraints apply to the payload size, and are expressed as bytes in UTF-8 encoding.

outputDetails

Contains details about the output of an execution history event.

resource
Required: Yes
Type: string

The action of the resource called by a task state.

resourceType
Required: Yes
Type: string

The service name of the resource in a task state.

TaskSucceededEventDetails

Description

Contains details about the successful completion of a task state.

Members
output
Type: string

The full JSON response from a resource when a task has succeeded. This response becomes the output of the related task. Length constraints apply to the payload size, and are expressed as bytes in UTF-8 encoding.

outputDetails

Contains details about the output of an execution history event.

resource
Required: Yes
Type: string

The action of the resource called by a task state.

resourceType
Required: Yes
Type: string

The service name of the resource in a task state.

TaskTimedOut

Description

The task token has either expired or the task associated with the token has already been closed.

Members
message
Type: string

TaskTimedOutEventDetails

Description

Contains details about a resource timeout that occurred during an execution.

Members
cause
Type: string

A more detailed explanation of the cause of the failure.

error
Type: string

The error code of the failure.

resource
Required: Yes
Type: string

The action of the resource called by a task state.

resourceType
Required: Yes
Type: string

The service name of the resource in a task state.

TooManyTags

Description

You've exceeded the number of tags allowed for a resource. See the Limits Topic in the Step Functions Developer Guide.

Members
message
Type: string
resourceName
Type: string

TracingConfiguration

Description

Selects whether or not the state machine's X-Ray tracing is enabled. Default is false

Members
enabled
Type: boolean

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

ValidateStateMachineDefinitionDiagnostic

Description

Describes an error found during validation. Validation errors found in the definition return in the response as diagnostic elements, rather than raise an exception.

Members
code
Required: Yes
Type: string

Identifying code for the diagnostic.

location
Type: string

Location of the issue in the state machine, if available.

For errors specific to a field, the location could be in the format: /States/<StateName>/<FieldName>, for example: /States/FailState/ErrorPath.

message
Required: Yes
Type: string

Message describing the diagnostic condition.

severity
Required: Yes
Type: string

A value of ERROR means that you cannot create or update a state machine with this definition.

ValidationException

Description

The input does not satisfy the constraints specified by an Amazon Web Services service.

Members
message
Type: string
reason
Type: string

The input does not satisfy the constraints specified by an Amazon Web Services service.