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

bash

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.

bash

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

Get details

bash

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.

bash

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

Edit Mutex Group

bash

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`. Archives or unarchives the mutex group. If true, Amplitude ignores all other arguments, marks the mutex group as deleted, and removes it from all child experiments' parent dependencies.

Example request

json

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

Response

A successful request returns a 200 OK response.

Request

curl

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

bash

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

Edit a 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

json

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

Response

A successful request returns a 200 OK response.

Request

curl

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

bash

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, Amplitude generates one.
`description`	Optional. Type: `string`. Description for the mutex group.
`evaluationMode`	Optional. Type: `string`. Mutex group evaluation mode. Options are `local` or `remote`. Defaults to `remote`.
`bucketingKey`	Optional. Type: `string`. The user property to bucket the user by. Defaults to `amplitude_id`.
`bucketingSalt`	Optional. Type: `string`. Mutex group bucketing salt. Defaults to a randomized string.
`slots`	Required. Type: `object array`. Array of `slots`. Up to 20 slots. Order matters.

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, inclusive. The sum of percentages across all slots must equal 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

json

{
    "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.

bash

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}]}'

Was this helpful?