A/B Testing REST API Reference
Use the A/B Testing REST API to create, update, and manage A/B tests for your custom skill.
To run A/B testing, you define existing and new skill experiences by adding conditional statements to the skill code of your live skill. These statements branch into the current skill experience, called the control version (C), or the new skill experience, called the treatment version (T1). You can use the A/B testing API to experiment with your new experience.
For more details, see About A/B Testing. You can also create and manage tests in the Alexa developer console.
API endpoint
The endpoint of the A/B Testing API is https://api.amazonalexa.com
.
Authentication
Each API request must have an authorization header whose value is the access token retrieved from Login with Amazon (LWA). For details, see Get an Access Token for SMAPI.
Operations
The A/B Testing API includes the following operations.
Operation | HTTP method and URI |
---|---|
| |
| |
| |
| |
| |
| |
| |
| |
| |
| |
| |
|
Create A/B test
Create a new A/B test for the specified skill. Here you define the percentage of customers to send to the new skill experience and the resulting metrics to collect.
You can also create an A/B test by using the create-experiment ASK CLI command.
Request
To create a new test, you make a POST
request to the /v1/skills/{skillId}/experiments
resource.
Request path and header example
POST /v1/skills/{skillId}/experiments/
Host: api.amazonalexa.com
Content-Type: application/json
Authorization: Bearer {access token}
Request path and header parameters
Parameter | Located in | Description | Type | Required |
---|---|---|---|---|
|
Path |
Identifies the skill associated with your A/B test. |
String |
Yes |
|
Header |
String |
Yes |
Request body example
{
"experiment": {
"name": "my_first_experiment",
"description": "experiment_1",
"type": "ENDPOINT_BASED",
"plannedDuration": "P4W",
"exposurePercentage": 20,
"metricConfigurations": [
{
"name": "Customer Friction",
"metricTypes": [
"GUARDRAIL"
],
"expectedChange": "INCREASE"
}
]
}
}
Request body properties
Property | Description | Type | Required |
---|---|---|---|
|
A/B test settings. |
Object |
Yes |
|
Unique name for your A/B test. |
String |
Yes |
|
Description of the hypothesis you set for your A/B test. |
String |
Yes |
|
Type of A/B test that you want to run for your skill.
|
String |
Yes |
|
Number of weeks you plan to run your A/B test. |
String |
Yes |
|
Percentage of unique customers that you plan to include in your A/B test. This number doesn't have to match your total users. |
Integer |
Yes |
|
List of A/B test metrics that you plan to use in your test. |
Array |
Yes |
|
Unique name of the test metric. |
String |
Yes |
|
List of metrics used in your A/B test. |
Array of strings |
Yes |
|
Direction that you expect a metric to trend during the testing. |
String |
Yes |
Response
A successful response returns HTTP 201 Created
, along with the experiment identifier in the Location
header. Use the URL in the Location header to track the test.
On error, the response returns the appropriate HTTP status code and includes a response body with an error code and human readable message.
Response body example
The response has no body.
Response body properties
The response has no body.
HTTP status codes
Status | Description |
---|---|
|
A/B test created successfully for the specified skill. |
|
Indicates that one or more properties in the request body aren't valid.
|
|
Request didn't include the authorization token, or the included token expired or isn't valid. Or, you don't have access to the resource. |
|
Indicates that the authorization token is valid, but the requested operation isn't allowed. |
|
Requested resource not found. |
|
Permitted rate limit, specified as number of requests per unit of time, exceeded. Retry the request by using exponential back-off. |
|
Error occurred on the server. Retry the request by using exponential back-off. |
|
Server is down for maintenance, overloaded, or otherwise unavailable to handle the incoming request. |
Delete A/B test
Delete the specified test.
Request
To remove an existing test, you make a DELETE
request to the /v1/skills/{skillId}/experiments
resource.
Request path and header example
DELETE /v1/skills/{skillId}/experiments/{experimentId}
Host: api.amazonalexa.com
Content-Type: application/json
Authorization: Bearer {access token}
Request path and header parameters
Parameter | Located in | Description | Type | Required |
---|---|---|---|---|
|
Path |
Identifies the skill associated with your A/B test. |
String |
Yes |
|
Path |
Identifies the A/B test. |
String |
Yes |
|
Header |
String |
Yes |
Request body example
The request has no body.
Request body properties
The request has no body.
Response
A successful response returns HTTP 204 No Content.
On error, the response returns the appropriate HTTP status code and includes a response body with an error code and human readable message.
Response body example
The response has no body.
Response body properties
The response has no body.
HTTP status codes
Status | Description |
---|---|
|
A/B test deleted successfully. |
|
Indicates that one or more properties in the request body aren't valid.
|
|
Request didn't include the authorization token, or the included token expired or isn't valid. Or, you don't have access to the resource. |
|
Indicates that the authorization token is valid, but the requested operation isn't allowed. |
|
Requested resource not found. |
|
Permitted rate limit, specified as number of requests per unit of time, exceeded. Retry the request by using exponential back-off. |
|
Error occurred on the server. Retry the request by using exponential back-off. |
|
Server is down for maintenance, overloaded, or otherwise unavailable to handle the incoming request. |
Get A/B test
Get the details an existing A/B test.
You can also retrieve an A/B test by using the get-experiment ASK CLI command.
Request
To get the test details, you make a GET
request to the /v1/skills/{skillId}/experiments/{experimentId}
resource.
Request path and header example
GET /v1/skills/{skillId}/experiments/{experimentId}
Host: api.amazonalexa.com
Content-Type: application/json
Authorization: Bearer {access token}
Accept: application/json
Request path and header parameters
Parameter | Located in | Description | Type | Required |
---|---|---|---|---|
|
Path |
Identifies the skill associated with your A/B test. |
String |
Yes |
|
Path |
Identifies the A/B test. |
String |
Yes |
|
Header |
String |
Yes |
Request body example
The request has no body.
Request body properties
The request has no body.
Response
A successful response returns HTTP 200 OK
, along with the details of the test.
On error, the response returns the appropriate HTTP status code and includes a response body with an error code and human readable message.
Response body example
{
"experiment": {
"name": "my_first_experiment",
"description": "experiment_1",
"type": "ENDPOINT_BASED",
"plannedDuration": "P3W",
"exposurePercentage": 0,
"metricConfigurations": [
{
"name": "Customer Friction",
"metricTypes": [
"GUARDRAIL"
],
"expectedChange": "INCREASE"
}
],
"state": "CREATED",
"history": {
"creationTime": "2021-04-19T18:43:48.383Z",
"startTime": "2021-04-19T18:43:48.383Z",
"stoppedReason": "string"
},
"trigger": {
"scheduledEndTime": "2021-04-19T18:43:48.383Z"
}
}
}
Response body properties
Property | Description | Type |
---|---|---|
|
A/B test settings. |
Object |
|
Unique name of the A/B test. Valid value: 1–255 characters. |
String |
|
Description of the hypothesis you set for your A/B test. |
String |
|
Type of A/B test that you want to run for your skill.
|
String |
|
Number of weeks you plan to run your A/B test. |
String |
|
Percentage of unique customers that you plan to include in your A/B test. This number doesn't have to match your total users. |
Integer |
|
List of A/B test metrics that you plan to use in your test. |
Array |
|
Unique name of the test metric. |
String |
|
List of metrics used in your A/B test. |
Array of strings |
|
Direction that you expect a metric to trend during the testing. |
String |
|
Number of overrides that exist for the test. |
Integer |
|
Current state of the test.
|
String |
|
History of an A/B test. |
Object |
|
Date and time the test was created or updated. |
String |
|
Date and time the test started. |
String |
|
Reason the test stopped. |
String |
|
Defines the triggers for the test. |
Object |
|
Expected end date and time of the test. |
String |
HTTP status codes
Status | Description |
---|---|
|
Response body contains the test details. |
|
Indicates that one or more properties in the request body aren't valid.
|
|
Request didn't include the authorization token, or the included token expired or isn't valid. Or, you don't have access to the resource. |
|
Indicates that the authorization token is valid, but the requested operation isn't allowed. |
|
Requested resource not found. |
|
Permitted rate limit, specified as number of requests per unit of time, exceeded. Retry the request by using exponential back-off. |
|
Error occurred on the server. Retry the request by using exponential back-off. |
|
Server is down for maintenance, overloaded, or otherwise unavailable to handle the incoming request. |
Get A/B test state
Get the current state of the specified test.
You can also retrieve the test state by using the get-experiment-state ASK CLI command.
Request
To get the test state, you make a GET
request to the /v1/skills/{skillId}/experiments/{experimentId}/state
resource.
Request path and header example
GET /v1/skills/{skillId}/experiments/{experimentId}/state
Host: api.amazonalexa.com
Content-Type: application/json
Authorization: Bearer {access token}
Accept: application/json
Request path and header parameters
Parameter | Located in | Description | Type | Required |
---|---|---|---|---|
|
Path |
Identifies the skill associated with your A/B test. |
String |
Yes |
|
Path |
Identifies the A/B test. |
String |
Yes |
|
Header |
String |
Yes |
Request body example
The request has no body.
Request body properties
The request has no body.
Response
A successful response returns HTTP 200 OK
, along with the state of the specified test.
On error, the response returns the appropriate HTTP status code and includes a response body with an error code and human readable message.
Response body example
{
"state": "CREATED"
}
Response body properties
Property | Description | Type |
---|---|---|
|
Current state of the test.
|
String |
HTTP status codes
Status | Description |
---|---|
|
Response body contains the test state. |
|
Indicates that one or more properties in the request body aren't valid.
|
|
Request didn't include the authorization token, or the included token expired or isn't valid. Or, you don't have access to the resource. |
|
Indicates that the authorization token is valid, but the requested operation isn't allowed. |
|
Requested resource not found. |
|
Permitted rate limit, specified as number of requests per unit of time, exceeded. Retry the request by using exponential back-off. |
|
Error occurred on the server. Retry the request by using exponential back-off. |
|
Server is down for maintenance, overloaded, or otherwise unavailable to handle the incoming request. |
Get customer treatment override
Get the current customer treatment override value of a specified A/B test. You use the override to test the new skill experience.
You can also retrieve the customer treatment override by using the get-customer-treatment-override ASK CLI command.
Request
To get the current customer treatment override, you make a GET
request to the /v1/skills/{skillId}/experiments/{experimentId}/treatmentOverrides
resource.
Request path and header example
GET /v1/skills/{skillId}/experiments/{experimentId}/treatmentOverrides/~current
Host: api.amazonalexa.com
Content-Type: application/json
Authorization: Bearer {access token}
Accept: application/json
Request path and header parameters
Parameter | Located in | Description | Type | Required |
---|---|---|---|---|
|
Path |
Identifies the skill associated with your A/B test. |
String |
Yes |
|
Path |
Identifies the A/B test. |
String |
Yes |
|
Header |
String |
Yes |
Request body example
The request has no body.
Request body properties
The request has no body.
Response
A successful response returns HTTP 200 OK
, along the current override count.
On error, the response returns the appropriate HTTP status code and includes a response body with an error code and human readable message.
Response body example
{
"treatmentId": "T1",
"treatmentOverrideCount": 2
}
Response body properties
Property | Description | Type |
---|---|---|
|
Testing group: control or new treatment. |
String |
|
Number of treatment overrides you set for your A/B test. |
Integer |
HTTP status codes
Status | Description |
---|---|
|
Response body contains the treatment override. |
|
Indicates that one or more properties in the request body aren't valid.
|
|
Request didn't include the authorization token, or the included token expired or isn't valid. Or, you don't have access to the resource. |
|
Indicates that the authorization token is valid, but the requested operation isn't allowed. |
|
Requested resource not found. |
|
Permitted rate limit, specified as number of requests per unit of time, exceeded. Retry the request by using exponential back-off. |
|
Error occurred on the server. Retry the request by using exponential back-off. |
|
Server is down for maintenance, overloaded, or otherwise unavailable to handle the incoming request. |
Get metric snapshot data
Get the metric data associated with the specified snapshot.
You can also retrieve the metric data by using the get-experiment-metric-snapshot ASK CLI command.
Request
To get metric data, you make a GET
request to the /v1/skills/{skillId}/experiments/{experimentId}/metricSnapshots
resource.
Request path and header example
GET /v1/skills/{skillId}/experiments/{experimentId}/metricSnapshots/{metricSnapshotId}
Host: api.amazonalexa.com
Content-Type: application/json
Authorization: Bearer {access token}
Accept: application/json
Request path and header parameters
Parameter | Located in | Description | Type | Required |
---|---|---|---|---|
|
Path |
Identifies the skill associated with your A/B test. |
String |
Yes |
|
Path |
Identifies the A/B test. |
String |
Yes |
|
Path |
Identifies the metric snapshot. |
String |
Yes |
|
Header |
String |
Yes |
Request body example
The request has no body.
Request body properties
The request has no body.
Response
A successful response returns HTTP 200 OK
, along with the metric data from the specified metric snapshot.
On error, the response returns the appropriate HTTP status code and includes a response body with an error code and human readable message.
Response body example
{
"status": "RELIABLE",
"statusReason": "["TAA Alarm","Message"]",
"metrics": [
{
"name": "Customer Friction",
"treatmentId": "C",
"values": {
"mean": 0,
"percentDiff": 0,
"confidenceIntervalLower": 0,
"confidenceIntervalUpper": 0,
"pValue": 0,
"userCount": 0
}
}
]
}
Response body properties
Property | Description | Type |
---|---|---|
|
State of the metric snapshot. |
String |
|
Reason why the metric snapshot status is unreliable. |
String |
|
List of metric snapshot values for your skill. |
Array of objects |
|
A unique name that identifies the A/B test metric. |
String |
|
Testing group assigned to the test that generated these metrics: control or new treatment. |
String |
|
Metric result values. |
Object |
|
Mean or average of each sample. |
Double |
|
Relative percent difference between the mean of the T1 group and the mean of the C group. |
Double |
|
Lower limit number of the confidence interval range. The confidence interval measures the probability that the mean falls within a range. |
Double |
|
Upper limit number of the confidence interval range. The confidence interval measures the probability that the mean falls within a range. |
Double |
|
Probability that the difference between the T1 and C means is due to random sampling errors. |
Double |
|
Number of users in the T1 sample*. |
Long |
HTTP status codes
Status | Description |
---|---|
|
Response body contains the metric data for the specified snapsnot. |
|
Indicates that one or more properties in the request body aren't valid.
|
|
Request didn't include the authorization token, or the included token expired or isn't valid. Or, you don't have access to the resource. |
|
Indicates that the authorization token is valid, but the requested operation isn't allowed. |
|
Requested resource not found. |
|
Permitted rate limit, specified as number of requests per unit of time, exceeded. Retry the request by using exponential back-off. |
|
Error occurred on the server. Retry the request by using exponential back-off. |
|
Server is down for maintenance, overloaded, or otherwise unavailable to handle the incoming request. |
List A/B tests
Get the list of A/B tests associated with the specified skill ID. This operation returns completed and in-progress tests.
You can also retrieve the list of A/B tests by using the list-experiments ASK CLI command.
Request
To list tests, you make a GET
request to the /v1/skills/{skillId}/experiments
resource.
Request path and header example
GET /v1/skills/{skillId}/experiments&maxResults={maxResults}&nextToken={nextToken}
Host: api.amazonalexa.com
Content-Type: application/json
Authorization: Bearer {access token}
Accept: application/json
Request path and header parameters
Parameter | Located in | Description | Type | Required |
---|---|---|---|---|
|
Path |
Identifies the skill associated with your A/B test. |
String |
Yes |
|
Query |
Maximum number of results to return in the response. |
Integer |
No |
|
Query |
Token from the previous response. If not included, the Alexa service returns the first page of results. |
String |
No |
|
Header |
String |
Yes |
Request body example
The request has no body.
Request body properties
The request has no body.
Response
A successful response returns HTTP 200 OK
, along with a list of A/B tests defined for your skill. If the number of results is too large, the response includes the paginationContext.nextToken
. Use the token in your next List A/B tests request to get the next page of results.
On error, the response returns the appropriate HTTP status code and includes a response body with an error code and human readable message.
Response body example
{
"experiments": [
{
"experimentId": "experiment.id.1",
"name": "my_first-experiment",
"state": "CREATED",
"experimentHistory": {
"creationTime": "2021-04-29T18:20:50.671Z",
"startTime": "2021-04-29T18:20:50.671Z",
"stoppedReason": "string"
}
}
]
}
Response body properties
Property | Description | Type |
---|---|---|
|
List of A/B tests defined for the specified skill |
Array of objects |
|
Unique identifier for the A/B test. |
String |
|
Unique name of the A/B test. |
String |
|
Current state of the test.
|
String |
|
History of an A/B test. |
Object |
|
Date and time the test was created or updated. |
String |
|
Date and time the test started. |
String |
|
Reason the text stopped. |
String |
|
Indicates there are more matching results. If present, the response contains a subset of the results. When there are no more matching results, |
Object |
|
Identifies the next set of results to return. The token expires in 24 hours. |
String |
HTTP status codes
Status | Description |
---|---|
|
Response body contains a list of A/B tests defined for the skill. |
|
Indicates that one or more properties in the request body aren't valid.
|
|
Request didn't include the authorization token, or the included token expired or isn't valid. Or, you don't have access to the resource. |
|
Indicates that the authorization token is valid, but the requested operation isn't allowed. |
|
Requested resource not found. |
|
Permitted rate limit, specified as number of requests per unit of time, exceeded. Retry the request by using exponential back-off. |
|
Error occurred on the server. Retry the request by using exponential back-off. |
|
Server is down for maintenance, overloaded, or otherwise unavailable to handle the incoming request. |
List metric snapshots
List metric snapshots associated with the experiment ID of an A/B test. A metric snapshot represents the metric data that's available for your test in a specific time range. This operation doesn't include detailed data about each metric snapshot. To get detailed analytics about a test, use the Get metric snapshot data operation.
You can also retrieve the list of snapshots by using the list-experiment-metric-snapshots ASK CLI command.
Request
To list snapshots, you make a GET
request to the /v1/skills/{skillId}/experiments/{experimentId}/metricSnapshots
resource.
Request path and header example
GET /v1/skills/{skillId}/experiments/{experimentId}/metricSnapshots&maxResults={maxResults}&nextToken={nextToken}
Host: api.amazonalexa.com
Content-Type: application/json
Authorization: Bearer {access token}
Accept: application/json
Request path and header parameters
Parameter | Located in | Description | Type | Required |
---|---|---|---|---|
|
Path |
Identifies the skill associated with your A/B test. |
String |
Yes |
|
Path |
Identifies the A/B test. |
String |
Yes |
|
Query |
Maximum number of results to return in the response. |
Integer |
No |
|
Query |
Token from the previous response. If not included, the Alexa service returns the first page of results. |
String |
No |
|
Header |
String |
Yes |
Request body example
The request has no body.
Request body properties
The request has no body.
Response
A successful response returns HTTP 200 OK
, along with a list of metric snapshots. If the number of results is too large, the response includes the paginationContext.nextToken
. Use the token in your next List metric snapshots request to get the next page of results.
On error, the response returns the appropriate HTTP status code and includes a response body with an error code and human readable message.
Response body example
{
"metricSnapshots": [
{
"metricSnapshotId": "snapshot.id.1",
"startDate": "2021-04-20T15:24:31.563Z",
"endDate": "2021-04-20T15:24:31.563Z"
},
{
"metricSnapshotId": "snapshot.id.2",
"startDate": "2021-04-21T15:24:31.563Z",
"endDate": "2021-04-21T15:24:31.563Z"
}
]
}
Response body properties
Property | Description | Type |
---|---|---|
|
List of metric snapshots for the specified A/B test. |
Array of objects |
|
Unique identifier for the metric snapshot of an A/B test. |
String |
|
Date and time the metric snapshot started. |
String |
|
Date and time the metric snapshot started. |
String |
|
Indicates there are more matching results. If present, the response contains a subset of the results. When there are no more matching results, |
Object |
|
Identifies the next set of results to return. The token expires in 24 hours. |
String |
HTTP status codes
Status | Description |
---|---|
|
Response body contains a list of metric snapshots for the specified A/B test. |
|
Indicates that one or more properties in the request body aren't valid.
|
|
Request didn't include the authorization token, or the included token expired or isn't valid. Or, you don't have access to the resource. |
|
Indicates that the authorization token is valid, but the requested operation isn't allowed. |
|
Requested resource not found. |
|
Permitted rate limit, specified as number of requests per unit of time, exceeded. Retry the request by using exponential back-off. |
|
Error occurred on the server. Retry the request by using exponential back-off. |
|
Server is down for maintenance, overloaded, or otherwise unavailable to handle the incoming request. |
Set customer treatment override
Set the testing group to C or T1 to override the customer treatment for the specified A/B test. You can use this operation to override the treatment for testing your skill experience.
You can also set the customer treatment override by using the set-customer-treatment-override ASK CLI command.
Request
To update the customer treatment override, you make a PUT
request to the ` /v1/skills/{skillId}/experiments/{experimentId}/treatmentOverrides` resource.
Request path and header example
PUT /v1/skills/{skillId}/experiments/{experimentId}/treatmentOverrides/~current
Host: api.amazonalexa.com
Content-Type: application/json
Authorization: Bearer {access token}
Request path and header parameters
Parameter | Located in | Description | Type | Required |
---|---|---|---|---|
|
Path |
Identifies the skill associated with your A/B test. |
String |
Yes |
|
Path |
Identifies the A/B test. |
String |
Yes |
|
Header |
String |
Yes |
Request body example
{
"treatmentId": "T1"
}
Request body properties
Property | Description | Type | Required |
---|---|---|---|
|
Testing group: control or new treatment. |
String |
Response
A successful response returns HTTP 202 Accepted
.
On error, the response returns the appropriate HTTP status code and includes a response body with an error code and human readable message.
Response body example
The response has no body.
Response body properties
The response has no body.
HTTP status codes
Status | Description |
---|---|
|
Override treatment updated successfully. |
|
Indicates that one or more properties in the request body aren't valid.
|
|
Request didn't include the authorization token, or the included token expired or isn't valid. Or, you don't have access to the resource. |
|
Indicates that the authorization token is valid, but the requested operation isn't allowed. |
|
Requested resource not found. |
|
Permitted rate limit, specified as number of requests per unit of time, exceeded. Retry the request by using exponential back-off. |
|
Error occurred on the server. Retry the request by using exponential back-off. |
|
Server is down for maintenance, overloaded, or otherwise unavailable to handle the incoming request. |
Update A/B test
Update the settings of an existing A/B test. To make changes, the test must be in the CREATED
state. You can't update an active test.
To update the exposure value of an active test, use Update exposure.
You can also update an A/B test by using the update-experiment ASK CLI command.
Request
To update a test, you make a POST
request to the /v1/skills/{skillId}/experiments
resource.
Request path and header example
POST /v1/skills/{skillId}/experiments/{experimentId}/properties
Host: api.amazonalexa.com
Content-Type: application/json
Authorization: Bearer {access token}
Request path and header parameters
Parameter | Located in | Description | Type | Required |
---|---|---|---|---|
|
Path |
Identifies the skill associated with your A/B test. |
String |
Yes |
|
Path |
Identifies the A/B test. |
String |
Yes |
|
Header |
String |
Yes |
Request body example
{
"experiment": {
"description": "experiment_1",
"plannedDuration": "P3W",
"exposurePercentage": 0,
"metricConfigurations": [
{
"name": "Customer Friction",
"metricTypes": [
"GUARDRAIL"
],
"expectedChange": "INCREASE"
}
]
}
}
Request body properties
Property | Description | Type | Required |
---|---|---|---|
|
A/B test settings. |
Object |
Yes |
|
Description of the hypothesis you set for your A/B test. |
String |
Yes |
|
Number of weeks you plan to run your A/B test. |
String |
Yes |
|
Percentage of unique customers that you plan to include in your A/B test. This number doesn't have to match your total users. |
Integer |
Yes |
|
List of A/B test metrics that you plan to use in your test. |
Array |
Yes |
|
Unique name of the test metric. |
String |
Yes |
|
List of metrics used in your A/B test. |
Array of strings |
Yes |
|
Direction that you expect a metric to trend during the testing. |
String |
Yes |
Response
A successful response returns HTTP 204 Success
.
On error, the response returns the appropriate HTTP status code and includes a response body with an error code and human readable message.
Response body example
The response has no body.
Response body properties
The response has no body.
HTTP status codes
Status | Description |
---|---|
|
A/B test values updated successfully. |
|
Indicates that one or more properties in the request body aren't valid.
|
|
Request didn't include the authorization token, or the included token expired or isn't valid. Or, you don't have access to the resource. |
|
Indicates that the authorization token is valid, but the requested operation isn't allowed. |
|
Requested resource not found. |
|
Permitted rate limit, specified as number of requests per unit of time, exceeded. Retry the request by using exponential back-off. |
|
Error occurred on the server. Retry the request by using exponential back-off. |
|
Server is down for maintenance, overloaded, or otherwise unavailable to handle the incoming request. |
Update A/B test state
Update the state of the specified A/B test.
Request
To update the test state, you make a POST
request to the /v1/skills/{skillId}/experiments/{experimentId}/state
resource.
Request path and header example
POST /v1/skills/{skillId}/experiments/{experimentId}/state
Host: api.amazonalexa.com
Content-Type: application/json
Authorization: Bearer {access token}
Request path and header parameters
Parameter | Located in | Description | Type | Required |
---|---|---|---|---|
|
Path |
Identifies the skill associated with your A/B test. |
String |
Yes |
|
Path |
Identifies the A/B test. |
String |
Yes |
|
Header |
String |
Yes |
Request body example
{
"targetState": "ENABLED"
}
Request body properties
Property | Description | Type | Required |
---|---|---|---|
|
New state of the test. |
String |
Yes |
|
Reason the test stopped. |
String |
No |
Response
A successful response returns HTTP 202 Accepted
, along with the experiment identifier in the Location
header. Use the URL in the Location header to track the test state.
On error, the response returns the appropriate HTTP status code and includes a response body with an error code and human readable message.
Response body example
The response has no body.
Response body properties
The response has no body.
HTTP status codes
Status | Description |
---|---|
|
Test state updated successfully. |
|
Indicates that one or more properties in the request body aren't valid.
|
|
Request didn't include the authorization token, or the included token expired or isn't valid. Or, you don't have access to the resource. |
|
Indicates that the authorization token is valid, but the requested operation isn't allowed. |
|
Requested resource not found. |
|
Permitted rate limit, specified as number of requests per unit of time, exceeded. Retry the request by using exponential back-off. |
|
Error occurred on the server. Retry the request by using exponential back-off. |
|
Server is down for maintenance, overloaded, or otherwise unavailable to handle the incoming request. |
Update exposure
Update the exposure value of an A/B test. You can use this operation when your test is in one of the following states:
CREATED
– Increase or decrease the exposure value. If you want to update other settings, use Update A/B test.RUNNING
– Increase your exposure value. To decrease your exposure value after you started the test, stop the test and create a new test.
You can also update the exposure value by using the update-exposure ASK CLI command.
Request
To update the exposure value, you make a POST
request to the /v1/skills/{skillId}/experiments
resource.
Request path and header example
POST /v1/skills/{skillId}/experiments/{experimentId}/exposurePercentage
Host: api.amazonalexa.com
Content-Type: application/json
Authorization: Bearer {access token}
Request path and header parameters
Parameter | Located in | Description | Type | Required |
---|---|---|---|---|
|
Path |
Identifies the skill associated with your A/B test. |
String |
Yes |
|
Path |
Identifies the A/B test. |
String |
Yes |
|
Header |
String |
Yes |
Request body example
{
"exposurePercentage": 60
}
Request body properties
Property | Description | Type | Required |
---|---|---|---|
|
New percentage of customers to be part of the test. If the test is running, you can increase the exposure percentage value of a running test, but not decrease it. |
Integer |
Yes |
Response
A successful response returns HTTP 204 No content
.
On error, the response returns the appropriate HTTP status code and includes a response body with an error code and human readable message.
Response body example
The response has no body.
Response body properties
The response has no body.
HTTP status codes
Status | Description |
---|---|
|
Test exposure value updated successfully. |
|
Indicates that one or more properties in the request body aren't valid.
|
|
Request didn't include the authorization token, or the included token expired or isn't valid. Or, you don't have access to the resource. |
|
Indicates that the authorization token is valid, but the requested operation isn't allowed. |
|
Requested resource not found. |
|
Permitted rate limit, specified as number of requests per unit of time, exceeded. Retry the request by using exponential back-off. |
|
Error occurred on the server. Retry the request by using exponential back-off. |
|
Server is down for maintenance, overloaded, or otherwise unavailable to handle the incoming request. |
Related topics
- A/B Testing Metric and Configuration Attributes
- Best Practices for A/B Tests
- Create and Manage A/B Tests in the Alexa Developer Console
Last updated: Aug 01, 2024