Experiment Management API Mutex Group Endpoints

Name	Description
List	List of mutex groups including their configuration details.
Edit Mutex Group	Edit mutex group.
Edit Mutex Group Slots	Edit mutex group slots.
Create	Create a new mutex.

List

1GET https://experiment.amplitude.com/api/1/mutexes

Fetch a list of mutex groups including their configuration details.

Query parameters

Name	Description
`limit`	The max number of mutex groups to be returned. Capped at 1000.
`cursor`	The offset to start the "page" of results from.

Response

A successful request returns a 200 OK response and a list of mutex groups encoded as JSON in the response body.

1curl --request GET \
2--url 'https://experiment.amplitude.com/api/1/mutexes?limit=1000' \
3--header 'Accept: application/json' \
4--header 'Authorization: Bearer <management-api-key>'

 1{
 2    "mutexes": [
 3        {
 4            "id": <id>,
 5            "projectId": <projectId>,
 6            "name": "mutex name",
 7            "key": "mutex-key",
 8            "description": null,
 9            "evaluationMode": "local",
10            "bucketingKey": "device_id",
11            "bucketingSalt": <bucketingSalt>,
12            "slots": [
13                {
14                    "name": "SLOT 1",
15                    "index": 1,
16                    "variantKey": "slot-1",
17                    "percentage": 95,
18                    "experiments": [
19                        123
20                    ],
21                    "holdouts": [
22                        456
23                    ],
24                    "individuals": [],
25                    "cohorts": []
26                },
27                {
28                    "name": "SLOT 2",
29                    "index": 2,
30                    "variantKey": "slot-2",
31                    "percentage": 5,
32                    "experiments": [],
33                    "holdouts": [],
34                    "individuals": [],
35                    "cohorts": []
36                }
37            ]
38        }
39    ],
40    "nextCursor": <cursorId>
41}

Get details

1GET https://experiment.amplitude.com/api/1/mutexes/<id>

Fetch the configuration details of a mutex group.

Path variables

Name	Description
`id`	Required. String. Mutex group's ID.

Response

A successful request returns a 200 OK response and a JSON object with the mutex group's details.

1curl --request GET \
2    --url 'https://experiment.amplitude.com/api/1/mutexes/<id>' \
3    --header 'Accept: application/json' \
4    --header 'Authorization: Bearer <management-api-key>'

 1{
 2    "id": <id>,
 3    "projectId": <projectId>,
 4    "name": "mutex name",
 5    "key": "mutex-key",
 6    "description": null,
 7    "evaluationMode": "local",
 8    "bucketingKey": "device_id",
 9    "bucketingSalt": <bucketingSalt>,
10    "slots": [
11        {
12            "name": "SLOT 1",
13            "index": 1,
14            "variantKey": "slot-1",
15            "percentage": 95,
16            "experiments": [
17                123
18            ],
19            "holdouts": [
20                456
21            ],
22            "individuals": [],
23            "cohorts": []
24        },
25        {
26            "name": "SLOT 2",
27            "index": 2,
28            "variantKey": "slot-2",
29            "percentage": 5,
30            "experiments": [],
31            "holdouts": [],
32            "individuals": [],
33            "cohorts": []
34        }
35    ]
36}

Edit Mutex Group

1PATCH https://experiment.amplitude.com/api/1/mutexes/{id}

Edit a mutex group.

Path variables

Name	Description
`id`	Required. String. Mutex group's ID.

Request body

Name	Requirement	Type	Description
`name`	Optional	string	The mutex group name.
`description`	Optional	string	The mutex group description.
`archive`	Optional	boolean	Property to archive or unarchive mutex group. If true, all other arguments are ignored and the mutex group will be set as deleted and removed from all child experiments’ parent dependencies.

Example request

1{
2    "name": "updated name",
3    "description": "updated description"
4}

Response

A successful request returns a 200 OK response.

Request

1curl --request PATCH \
2    --url 'https://experiment.amplitude.com/api/1/mutexes/<id>' \
3    --header 'Content-Type: application/json' \
4    --header 'Accept: application/json' \
5    --header 'Authorization: Bearer <management-api-key>' \
6    --data '{"name": "updated name"}'

Edit Mutex Group Slots

1PATCH https://experiment.amplitude.com/api/1/mutexes/{id}/slots/{slotIndex}

Edit an mutex group slot.

Path variables

Name	Description
`id`	Required. String. Mutex group's ID.
`slotIndex`	Required. Number. Slot index of this mutex.

Request body

Name	Requirement	Type	Description
`experiments`	Optional	number array	List of experiment ids to be included.
`holdouts`	Optional	number array	List of holdout group ids to be included.
`individuals`	Optional	string array	List of user ids or device ids to be included.

Example request

1{
2    "experiments": [123, 456],
3    "individuals": ["x@amplitude.com", "y@amplitude.com", "abcde-12345"]
4}

Response

A successful request returns a 200 OK response.

Request

1curl --request PATCH \
2    --url 'https://experiment.amplitude.com/api/1/mutexes/<id>/slots/<slotIndex>' \
3    --header 'Content-Type: application/json' \
4    --header 'Accept: application/json' \
5    --header 'Authorization: Bearer <management-api-key>' \
6    --data '{"experiments": [123, 456]}'

Create

1POST https://experiment.amplitude.com/api/1/mutexes

Create a new mutex group.

Request body

Name	Requirement	Type	Description
`projectId`	Required	number	Project id of the mutex group.
`name`	Required	string	The mutex group name.
`key`	Optional	string	The mutex group key. Must be unique across all flags, experiments, holdout groups, and mutex groups. If not specified, one will be generated.
`description`	Optional	string	Description for the mutex group.
`evaluationMode`	Optional	string	Mutex group evaluation mode; options include `local` or `remote`. Defaulted to `remote`.
`bucketingKey`	Optional	string	The user property to bucket the user by. Defaulted to "amplitude_id"
`bucketingSalt`	Optional	string	Mutex Group bucketing salt. Defaulted to a randomized string.
`slots`	Required	object array	Array of `slots`. Up to 20 slots. Order matters.

slots

The slots field contains these objects.

Name	Requirement	Type	Description
`percentage`	Required	number	The percentage of traffic to this slot. An integer between 1 and 100, inclusively. The sum of percentages in all slots must adds up to 100.
`experiments`	Optional	string array	List of experiment ids to be included.
`holdouts`	Optional	number array	List of holdout group id to be included.
`individuals`	Optional	number array	List of user ids or device ids to be included.

Example request

 1{
 2    "projectId":"<projectId>",
 3    "name": "Example Mutex Group",
 4    "key": "example-mutex",
 5    "description": "An example mutex group",
 6    "evaluationMode": "remote",
 7      "slots": [
 8          {
 9              "percentage": 40,
10              "experiments": [123],
11              "holdouts": [456]
12          },
13          {
14              "percentage": 60,
15              "experiments": [789],
16              "individuals": ["x@amplitude.com"]
17          }
18    ]
19}

Response

A successful request returns a 200 OK response and a JSON object with the mutex group's id and url.

1curl --request POST \
2    --url 'https://experiment.amplitude.com/api/1/mutexes' \
3    --header 'Content-Type: application/json' \
4    --header 'Accept: application/json' \
5    --header 'Authorization: Bearer <management-api-key>' \
6    --data '{"projectId":"<projectId>","slots":[{"percentage":40},{"percentage":60}]}'

1{
2    "id": "<id>",
3    "url": "http://experiment.amplitude.com/amplitude/experiments/grouped-experiments"
4}