| Name | Description | | --------------------------------------------------- | ----------------------------------------------------------- | | [List mutex groups](#list-mutex-groups) | List mutex groups with their configuration details. | | [Get mutex group details](#get-mutex-group-details) | Get the configuration details of a single mutex group. | | [Edit a mutex group](#edit-a-mutex-group) | Update a mutex group's name, description, or archive state. | | [Edit mutex group slots](#edit-mutex-group-slots) | Update the contents of a mutex group slot. | | [Create a mutex group](#create-a-mutex-group) | Create a new mutex group. | {% callout type="note" heading="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](/docs/apis/experiment/experiment-management-api#regions). {% /callout %} ## 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. {% code-group %} ```bash Request curl --request GET \ --url 'https://experiment.amplitude.com/api/1/mutexes?limit=1000' \ --header 'Accept: application/json' \ --header 'Authorization: Bearer ' ``` ```json Response { "mutexes": [ { "id": , "projectId": , "name": "mutex name", "key": "mutex-key", "description": null, "evaluationMode": "local", "bucketingKey": "device_id", "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": } ``` {% /code-group %} ## Get mutex group details ```bash GET https://experiment.amplitude.com/api/1/mutexes/ ``` 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. {% code-group %} ```bash Request curl --request GET \ --url 'https://experiment.amplitude.com/api/1/mutexes/' \ --header 'Accept: application/json' \ --header 'Authorization: Bearer ' ``` ```bash Response { "id": , "projectId": , "name": "mutex name", "key": "mutex-key", "description": null, "evaluationMode": "local", "bucketingKey": "device_id", "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": [] } ] } ``` {% /code-group %} ## 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. | {% callout type="example" heading="Example request" %} ```json { "name": "updated name", "description": "updated description" } ``` {% /callout %} ### Response A successful request returns a `200 OK` response. {% callout type="example" heading="Request" %} ```curl curl --request PATCH \ --url 'https://experiment.amplitude.com/api/1/mutexes/' \ --header 'Content-Type: application/json' \ --header 'Accept: application/json' \ --header 'Authorization: Bearer ' \ --data '{"name": "updated name"}' ``` {% /callout %} ## 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. | {% callout type="example" heading="Example request" %} ```json { "experiments": [123, 456], "individuals": ["x@amplitude.com", "y@amplitude.com", "abcde-12345"] } ``` {% /callout %} ### Response A successful request returns a `200 OK` response. {% callout type="example" heading="Request" %} ```curl curl --request PATCH \ --url 'https://experiment.amplitude.com/api/1/mutexes//slots/' \ --header 'Content-Type: application/json' \ --header 'Accept: application/json' \ --header 'Authorization: Bearer ' \ --data '{"experiments": [123, 456]}' ``` {% /callout %} ## 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`](#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. | {% callout type="example" heading="Example request" %} ```json { "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"] } ] } ``` {% /callout %} ### Response A successful request returns a `200 OK` response and a JSON object with the mutex group's id and url. {% code-group %} ```bash Request curl --request POST \ --url 'https://experiment.amplitude.com/api/1/mutexes' \ --header 'Content-Type: application/json' \ --header 'Accept: application/json' \ --header 'Authorization: Bearer ' \ --data '{"projectId":"","slots":[{"percentage":40},{"percentage":60}]}' ``` ```json Response { "id": "", "url": "http://experiment.amplitude.com/amplitude/experiments/grouped-experiments" } ``` {% /code-group %}