CreateStateMachineAlias - Amazon Step Functions
Services or capabilities described in Amazon Web Services documentation might vary by Region. To see the differences applicable to the China Regions, see Getting Started with Amazon Web Services in China (PDF).


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:

Request Syntax

{ "description": "string", "name": "string", "routingConfiguration": [ { "stateMachineVersionArn": "string", "weight": number } ] }

Request Parameters

For information about the parameters that are common to all actions, see Common Parameters.

The request accepts the following data in JSON format.


A description for the state machine alias.

Type: String

Length Constraints: Maximum length of 256.

Required: No


The name of the state machine alias.

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

Type: String

Length Constraints: Minimum length of 1. Maximum length of 80.

Pattern: ^(?=.*[a-zA-Z_\-\.])[a-zA-Z0-9_\-\.]+$

Required: Yes


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.

Type: Array of RoutingConfigurationListItem objects

Array Members: Minimum number of 1 item. Maximum number of 2 items.

Required: Yes

Response Syntax

{ "creationDate": number, "stateMachineAliasArn": "string" }

Response Elements

If the action is successful, the service sends back an HTTP 200 response.

The following data is returned in JSON format by the service.


The date the state machine alias was created.

Type: Timestamp


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

Type: String

Length Constraints: Minimum length of 1. Maximum length of 256.


For information about the errors that are common to all actions, see Common Errors.


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

HTTP Status Code: 400


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

HTTP Status Code: 400


The provided name is not valid.

HTTP Status Code: 400


Could not find the referenced resource.

HTTP Status Code: 400


The request would cause a service quota to be exceeded.

HTTP Status Code: 402

HTTP Status Code: 400


The specified state machine is being deleted.

HTTP Status Code: 400


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

HTTP Status Code: 400

See Also

For more information about using this API in one of the language-specific Amazon SDKs, see the following: