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

GET 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.

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

{
    "mutexes": [
        {
            "id": <id>,
            "projectId": <projectId>,
            "name": "mutex name",
            "key": "mutex-key",
            "description": null,
            "evaluationMode": "local",
            "bucketingKey": "device_id",
            "bucketingSalt": <bucketingSalt>,
            "slots": [
                {
                    "name": "SLOT 1",
                    "index": 1,
                    "variantKey": "slot-1",
                    "percentage": 95,
                    "experiments": [
                        123
                    ],
                    "holdouts": [
                        456
                    ],
                    "individuals": [],
                    "cohorts": []
                },
                {
                    "name": "SLOT 2",
                    "index": 2,
                    "variantKey": "slot-2",
                    "percentage": 5,
                    "experiments": [],
                    "holdouts": [],
                    "individuals": [],
                    "cohorts": []
                }
            ]
        }
    ],
    "nextCursor": <cursorId>
}

Get details

GET 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.

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

{
    "id": <id>,
    "projectId": <projectId>,
    "name": "mutex name",
    "key": "mutex-key",
    "description": null,
    "evaluationMode": "local",
    "bucketingKey": "device_id",
    "bucketingSalt": <bucketingSalt>,
    "slots": [
        {
            "name": "SLOT 1",
            "index": 1,
            "variantKey": "slot-1",
            "percentage": 95,
            "experiments": [
                123
            ],
            "holdouts": [
                456
            ],
            "individuals": [],
            "cohorts": []
        },
        {
            "name": "SLOT 2",
            "index": 2,
            "variantKey": "slot-2",
            "percentage": 5,
            "experiments": [],
            "holdouts": [],
            "individuals": [],
            "cohorts": []
        }
    ]
}

Edit Mutex Group

PATCH 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	Description
`name`	Optional. Type: `string`. The mutex group name.
`description`	Optional. Type: `string`. The mutex group description.
`archive`	Optional. Type: `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

{
    "name": "updated name",
    "description": "updated description"
}

Response

A successful request returns a 200 OK response.

Request

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

Edit Mutex Group Slots

PATCH 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	Description
`experiments`	Optional. Type: `number array`. List of experiment ids to be included.
`holdouts`	Optional. Type: `number array`. List of holdout group ids to be included.
`individuals`	Optional. Type: `string array`. List of user ids or device ids to be included.

Example request

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

Response

A successful request returns a 200 OK response.

Request

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

Create

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

Create a new mutex group.

Request body

Name	Description
`projectId`	Required. Type: `number`. Project id of the mutex group.
`name`	Required. Type: `string`. The mutex group name.
`key`	Optional. Type: `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. Type: `string`. Description for the mutex group.
`evaluationMode`	Optional
`bucketingKey`	Optional
`bucketingSalt`	Optional
`slots`	Required

slots

The slots field contains these objects.

Name	Description
`percentage`	Required. Type: `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. Type: `string array`. List of experiment ids to be included.
`holdouts`	Optional. Type: `number array`. List of holdout group id to be included.
`individuals`	Optional. Type: `number array`. List of user ids or device ids to be included.

Example request

{
    "projectId":"<projectId>",
    "name": "Example Mutex Group",
    "key": "example-mutex",
    "description": "An example mutex group",
    "evaluationMode": "remote",
  	"slots": [
      	{
      		"percentage": 40,
          	"experiments": [123],
          	"holdouts": [456]
      	},
      	{
      		"percentage": 60,
          	"experiments": [789],
          	"individuals": ["x@amplitude.com"]
      	}
    ]
}

Response

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

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

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