StartExperimentRun
Starts an experiment run for the specified experiment definition. An experiment run delivers treatments to the target audience and collects metrics. You can start multiple experiment runs from the same experiment definition.
Note
Billing for this experiment begins when you call this operation and continues until the experiment is stopped. For pricing details, see AWS AppConfig pricing
Request Syntax
POST /applications/ApplicationIdentifier/experimentdefinitions/ExperimentDefinitionIdentifier/experimentruns HTTP/1.1
Content-type: application/json
{
"DeploymentParameters": {
"DynamicExtensionParameters": {
"string" : "string"
},
"Tags": {
"string" : "string"
}
},
"Description": "string",
"ExposurePercentage": number,
"Tags": {
"string" : "string"
},
"TreatmentOverrides": { ... }
}URI Request Parameters
The request uses the following URI parameters.
- ApplicationIdentifier
-
The application ID or name.
Length Constraints: Minimum length of 1. Maximum length of 2048.
Required: Yes
- ExperimentDefinitionIdentifier
-
The experiment definition ID or name.
Length Constraints: Minimum length of 1. Maximum length of 2048.
Required: Yes
Request Body
The request accepts the following data in JSON format.
- DeploymentParameters
-
The deployment parameters for the experiment run, including a KMS key identifier for encryption.
Type: DeploymentParameters object
Required: No
- Description
-
A description of this experiment run.
Type: String
Length Constraints: Minimum length of 0. Maximum length of 1024.
Required: No
- ExposurePercentage
-
The percentage of the target audience to expose to treatments. Set to 0 to validate the experiment before exposing production users.
Type: Float
Valid Range: Minimum value of 0.0. Maximum value of 100.0.
Required: No
- Tags
-
The tags to assign to the experiment run.
Type: String to string map
Map Entries: Minimum number of 0 items. Maximum number of 50 items.
Key Length Constraints: Minimum length of 1. Maximum length of 128.
Value Length Constraints: Maximum length of 256.
Required: No
- TreatmentOverrides
-
Treatment assignment overrides that assign specific entity IDs to treatments directly, bypassing random assignment.
Type: TreatmentOverrides object
Note: This object is a Union. Only one member of this object can be specified or returned.
Required: No
Response Syntax
HTTP/1.1 201
Content-type: application/json
{
"ApplicationId": "string",
"Description": "string",
"EndedAt": "string",
"ExperimentDefinitionId": "string",
"ExperimentDefinitionSnapshot": {
"ApplicationId": "string",
"AudienceDescription": "string",
"AudienceRule": "string",
"ConfigurationProfileId": "string",
"Control": {
"Description": "string",
"FlagValue": {
"AttributeValues": {
"string" : { ... }
},
"Enabled": boolean
},
"Key": "string",
"Weight": number
},
"EnvironmentId": "string",
"FlagKey": "string",
"Hypothesis": "string",
"Id": "string",
"LaunchCriteria": "string",
"Name": "string",
"Treatments": [
{
"Description": "string",
"FlagValue": {
"AttributeValues": {
"string" : { ... }
},
"Enabled": boolean
},
"Key": "string",
"Weight": number
}
]
},
"ExposurePercentage": number,
"Result": {
"ExecutiveSummary": "string",
"ReasonsNotToLaunch": "string",
"ReasonsToLaunch": "string"
},
"Run": number,
"StartedAt": "string",
"Status": "string",
"TreatmentOverrides": { ... },
"UpdatedAt": "string"
}Response Elements
If the action is successful, the service sends back an HTTP 201 response.
The following data is returned in JSON format by the service.
- ApplicationId
-
The application ID.
Type: String
Pattern:
[a-z0-9]{4,7} - Description
-
A description of the experiment run.
Type: String
Length Constraints: Minimum length of 0. Maximum length of 1024.
- EndedAt
-
The date and time the experiment run ended, in ISO 8601 format.
Type: Timestamp
- ExperimentDefinitionId
-
The experiment definition ID.
Type: String
Pattern:
[a-z0-9]{4,7} - ExperimentDefinitionSnapshot
-
A snapshot of the experiment definition at the time the run was started.
Type: ExperimentDefinitionSnapshot object
- ExposurePercentage
-
The percentage of the target audience exposed to treatments.
Type: Float
Valid Range: Minimum value of 0.0. Maximum value of 100.0.
- Result
-
The result of the experiment run, including the executive summary and launch decision rationale.
Type: ExperimentRunResult object
- Run
-
The experiment run number.
Type: Integer
- StartedAt
-
The date and time the experiment run started, in ISO 8601 format.
Type: Timestamp
- Status
-
The current status of the experiment run. Valid values:
RUNNING,DONE.Type: String
Valid Values:
RUNNING | DONE - TreatmentOverrides
-
Treatment assignment overrides that assign specific entity IDs to treatments.
Type: TreatmentOverrides object
Note: This object is a Union. Only one member of this object can be specified or returned.
- UpdatedAt
-
The date and time the experiment run was last updated, in ISO 8601 format.
Type: Timestamp
Errors
For information about the errors that are common to all actions, see Common Error Types.
- BadRequestException
-
The input fails to satisfy the constraints specified by an AWS service.
- Details
-
Detailed information about the input that failed to satisfy the constraints specified by a call.
HTTP Status Code: 400
- ConflictException
-
The request could not be processed because of conflict in the current state of the resource.
HTTP Status Code: 409
- InternalServerException
-
There was an internal failure in the AWS AppConfig service.
HTTP Status Code: 500
- ResourceNotFoundException
-
The requested resource could not be found.
HTTP Status Code: 404
Examples
Example
This example illustrates one usage of StartExperimentRun.
Sample Request
POST /applications/abc1234/experimentdefinitions/bsxyd7k/experimentruns HTTP/1.1
Host: appconfig.us-east-1.amazonaws.com
Content-Type: application/json
User-Agent: aws-cli
X-Amz-Date: 20210916T175455Z
Authorization: AWS4-HMAC-SHA256 Credential=AKIAIOSFODNN7EXAMPLE/20210916/us-east-1/appconfig/aws4_request, SignedHeaders=content-type;host;x-amz-date, Signature=39c3b3042cd2aEXAMPLE
Content-Length: 28
{
"ExposurePercentage": 50.0
}Sample Response
{
"ApplicationId": "abc1234",
"ExperimentDefinitionId": "bsxyd7k",
"ExperimentDefinitionSnapshot": {
"ApplicationId": "abc1234",
"AudienceRule": "(eq $country \"US\")",
"ConfigurationProfileId": "ur8hx2f",
"Control": {
"FlagValue": {
"Enabled": false
},
"Key": "c",
"Weight": 50.0
},
"EnvironmentId": "env1234",
"FlagKey": "my-feature-flag",
"Id": "bsxyd7k",
"Name": "Example-Experiment-Definition",
"Treatments": [
{
"FlagValue": {
"Enabled": true
},
"Key": "t1",
"Weight": 50.0
}
]
},
"ExposurePercentage": 50.0,
"Run": 1,
"StartedAt": "2026-06-16T17:57:10.046Z",
"Status": "RUNNING",
"UpdatedAt": "2026-06-16T17:57:10.567Z"
}See Also
For more information about using this API in one of the language-specific AWS SDKs, see the following:
