CreateLaunch - CloudWatch Evidently


Creates a launch of a given feature. Before you create a launch, you must create the feature to use for the launch.

You can use a launch to safely validate new features by serving them to a specified percentage of your users while you roll out the feature. You can monitor the performance of the new feature to help you decide when to ramp up traffic to more users. This helps you reduce risk and identify unintended consequences before you fully launch the feature.

Don't use this operation to update an existing launch. Instead, use UpdateLaunch.

Request Syntax

POST /projects/project/launches HTTP/1.1 Content-type: application/json { "description": "string", "groups": [ { "description": "string", "feature": "string", "name": "string", "variation": "string" } ], "metricMonitors": [ { "metricDefinition": { "entityIdKey": "string", "eventPattern": "string", "name": "string", "unitLabel": "string", "valueKey": "string" } } ], "name": "string", "randomizationSalt": "string", "scheduledSplitsConfig": { "steps": [ { "groupWeights": { "string" : number }, "segmentOverrides": [ { "evaluationOrder": number, "segment": "string", "weights": { "string" : number } } ], "startTime": number } ] }, "tags": { "string" : "string" } }

URI Request Parameters

The request uses the following URI parameters.


The name or ARN of the project that you want to create the launch in.

Length Constraints: Minimum length of 0. Maximum length of 2048.

Pattern: (^[a-zA-Z0-9._-]*$)|(arn:[^:]*:[^:]*:[^:]*:[^:]*:project/[a-zA-Z0-9._-]*)

Required: Yes

Request Body

The request accepts the following data in JSON format.


An optional description for the launch.

Type: String

Length Constraints: Minimum length of 0. Maximum length of 160.

Pattern: .*

Required: No


An array of structures that contains the feature and variations that are to be used for the launch.

Type: Array of LaunchGroupConfig objects

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

Required: Yes


An array of structures that define the metrics that will be used to monitor the launch performance.

Type: Array of MetricMonitorConfig objects

Array Members: Minimum number of 0 items. Maximum number of 3 items.

Required: No


The name for the new launch.

Type: String

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

Pattern: ^[-a-zA-Z0-9._]*$

Required: Yes


When Evidently assigns a particular user session to a launch, it must use a randomization ID to determine which variation the user session is served. This randomization ID is a combination of the entity ID and randomizationSalt. If you omit randomizationSalt, Evidently uses the launch name as the randomizationSalt.

Type: String

Length Constraints: Minimum length of 0. Maximum length of 127.

Pattern: .*

Required: No


An array of structures that define the traffic allocation percentages among the feature variations during each step of the launch.

Type: ScheduledSplitsLaunchConfig object

Required: No


Assigns one or more tags (key-value pairs) to the launch.

Tags can help you organize and categorize your resources. You can also use them to scope user permissions by granting a user permission to access or change only resources with certain tag values.

Tags don't have any semantic meaning to AWS and are interpreted strictly as strings of characters.

You can associate as many as 50 tags with a launch.

For more information, see Tagging AWS resources.

Type: String to string map

Key Length Constraints: Minimum length of 1. Maximum length of 128.

Key Pattern: ^(?!aws:)[a-zA-Z+-=._:/]+$

Value Length Constraints: Minimum length of 0. Maximum length of 256.

Required: No

Response Syntax

HTTP/1.1 200 Content-type: application/json { "launch": { "arn": "string", "createdTime": number, "description": "string", "execution": { "endedTime": number, "startedTime": number }, "groups": [ { "description": "string", "featureVariations": { "string" : "string" }, "name": "string" } ], "lastUpdatedTime": number, "metricMonitors": [ { "metricDefinition": { "entityIdKey": "string", "eventPattern": "string", "name": "string", "unitLabel": "string", "valueKey": "string" } } ], "name": "string", "project": "string", "randomizationSalt": "string", "scheduledSplitsDefinition": { "steps": [ { "groupWeights": { "string" : number }, "segmentOverrides": [ { "evaluationOrder": number, "segment": "string", "weights": { "string" : number } } ], "startTime": number } ] }, "status": "string", "statusReason": "string", "tags": { "string" : "string" }, "type": "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.


A structure that contains the configuration of the launch that was created.

Type: Launch object


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


You do not have sufficient permissions to perform this action.

HTTP Status Code: 403


A resource was in an inconsistent state during an update or a deletion.

HTTP Status Code: 409


The request references a resource that does not exist.

HTTP Status Code: 404


The request would cause a service quota to be exceeded.

HTTP Status Code: 402


The value of a parameter in the request caused an error.

HTTP Status Code: 400



The following example creates a launch with two segment overrides. The first segment override to be evaluated is the one with evaluationOrder of 0, and it assigns the V1 variation to half of the Washington state users segment. The other half of this segment moves on to be evaluated by the next segment override. This next segment override assigns all users that match it to the two variations. Any remaining users who don't match either segment are assigned to the V1 variation as specified in the groups structure.

{ "description": "My sample launch with segments", "groups": [{ "description": "Default launch group for users who don't match a segment", "feature": "Feature-1", "name": "Launch-group-name", "variation": "V1" }], "metricMonitors": [{ "metricDefinition": { "entityIdKey": "userDetails.userID", "eventPattern": "metric-pattern", "name": "PageLoadTime", "valueKey": "details.pageLoadTime" } }], "name": "My test launch", "scheduledSplitsConfig": { "steps": [{ "startTime": 1655163501, "groupWeights": { "V1": 50000, "V2": 50000 }, "segmentOverrides": [{ "segment": "Washington-state-users", "evaluationOrder": 0, "weights": { "V1": 50000, "V2": 0 } }, { "segment": "US-users", "evaluationOrder": 1, "weights": { "V1": 70000, "V2": 30000 } } ] }] } }

See Also

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