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

> **Note:** 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](https://amplitude.com/docs/apis/experiment/experiment-management-api#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.

#### Request

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

#### Response

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

#### Request

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

#### Response

```bash
{
    "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 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:** 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/<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:** 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/<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`](#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:** 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.

#### 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 <management-api-key>' \
    --data '{"projectId":"<projectId>","slots":[{"percentage":40},{"percentage":60}]}'
```

#### Response

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