Experiment Management API Mutex Group Endpoints

Name	Description
List mutex groups	List mutex groups with their configuration details.
Get mutex group details	Get the configuration details of a single mutex group.
Edit a mutex group	Update a mutex group's name, description, or archive state.
Edit mutex group slots	Update the contents of a mutex group slot.
Create a mutex group	Create a new mutex group.

EU data residency

The examples on this page use the default base URL https://experiment.amplitude.com. If your project uses Amplitude's EU data center, use https://experiment.eu.amplitude.com instead. For more information, refer to Regions.

List mutex groups

bash

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

Returns a list of mutex groups with their configuration details.

Query parameters

Name	Description
`limit`	The maximum number of mutex groups to return. 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 mutex group details

bash

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

Returns the configuration details of a single mutex group.

Path variables

Name	Type	Required	Description
`id`	String	Yes	The 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 a mutex group

bash

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

Updates a mutex group's name, description, or archive state.

Path variables

Name	Type	Required	Description
`id`	String	Yes	The mutex group's ID.

Request body

Name	Type	Required	Description
`name`	String	No	The mutex group name.
`description`	String	No	The mutex group description.
`archive`	Boolean	No	Archives or unarchives the mutex group. When `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}

Updates the contents of a mutex group slot.

Path variables

Name	Type	Required	Description
`id`	String	Yes	The mutex group's ID.
`slotIndex`	Number	Yes	The slot index of this mutex.

Request body

Name	Type	Required	Description
`experiments`	Number array	No	List of experiment IDs to include.
`holdouts`	Number array	No	List of holdout group IDs to include.
`individuals`	String array	No	List of user IDs or device IDs to include.

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 a mutex group

bash

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

Creates a new mutex group.

Request body

Name	Type	Required	Description
`projectId`	Number	Yes	Project ID of the mutex group.
`name`	String	Yes	The mutex group name.
`key`	String	No	The mutex group key. Must be unique across all flags, experiments, holdout groups, and mutex groups. Amplitude generates a key when you don't specify one.
`description`	String	No	Description for the mutex group.
`evaluationMode`	String	No	Mutex group evaluation mode. Options are `local` or `remote`. Defaults to `remote`.
`bucketingKey`	String	No	The user property to bucket the user by. Defaults to `amplitude_id`.
`bucketingSalt`	String	No	Mutex group bucketing salt. Defaults to a randomized string.
`slots`	Object array	Yes	Array of `slots`. Up to 20 slots. Order matters.

slots

The slots field contains these objects.

Name	Type	Required	Description
`percentage`	Number	Yes	The percentage of traffic to this slot. An integer between 1 and 100, inclusive. Percentages across all slots must sum to 100.
`experiments`	String array	No	List of experiment IDs to include.
`holdouts`	Number array	No	List of holdout group IDs to include.
`individuals`	Number array	No	List of user IDs or device IDs to include.

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?