--- title: Experiment Management API Mutex Group Endpoints description: product: experiment token_estimate: 2226 --- # Experiment Management API Mutex Group Endpoints > For AI agents: a documentation index is available at [/docs/llms.txt](/docs/llms.txt). Append `.md` to any page URL for markdown, or send `Accept: text/markdown`. | Name | Description | | --- | --- | | [List](#list) | List of mutex groups including their configuration details. | | [Edit Mutex Group](#edit-mutex-group) | Edit mutex group. | | [Edit Mutex Group Slots](#edit-mutex-group-slots) | Edit mutex group slots. | | [Create](#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. #### Request ```bash curl --request GET \ --url 'https://experiment.amplitude.com/api/1/mutexes?limit=1000' \ --header 'Accept: application/json' \ --header 'Authorization: Bearer ' ``` #### Response ```json { "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": } ``` ## Get details ```bash GET https://experiment.amplitude.com/api/1/mutexes/ ``` 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. #### Request ```bash curl --request GET \ --url 'https://experiment.amplitude.com/api/1/mutexes/' \ --header 'Accept: application/json' \ --header 'Authorization: Bearer ' ``` #### Response ```bash { "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": [] } ] } ``` ## 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:** Example request > > ```json > { > "name": "updated name", > "description": "updated description" > } > ``` ### Response A successful request returns a `200 OK` response. > **Example:** 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"}' > ``` ## 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:** Example request > > ```json > { > "experiments": [123, 456], > "individuals": ["x@amplitude.com", "y@amplitude.com", "abcde-12345"] > } > ``` ### Response A successful request returns a `200 OK` response. > **Example:** 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]}' > ``` ## 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`](#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:** 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"] > } > ] > } > ``` ### Response A successful request returns a `200 OK` response and a JSON object with the mutex group's id and url. #### Request ```bash 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}]}' ``` #### Response ```json { "id": "", "url": "http://experiment.amplitude.com/amplitude/experiments/grouped-experiments" } ```