| Name                        | Description                                           |
| --------------------------- | ----------------------------------------------------- |
| [List](#list)               | List holdout groups with their configuration details. |
| [Get details](#get-details) | Get the configuration details of a holdout group.     |
| [Edit](#edit)               | Edit a holdout group.                                 |
| [Create](#create)           | Create a new holdout 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

```bash
GET https://experiment.amplitude.com/api/1/holdouts
```

Fetch a list of holdout groups with their configuration details.

### Query parameters

| Name     | Type    | Required | Description                                                     |
| -------- | ------- | -------- | --------------------------------------------------------------- |
| `limit`  | Integer | No       | The maximum number of holdout groups to return. Capped at 1000. |
| `cursor` | String  | No       | The offset to start the page of results from.                   |

### Response

A successful request returns a `200 OK` response and a list of holdout groups encoded as JSON in the response body.

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

```json Response
{
  	"holdouts": [
      	{
            "id": <holdoutId>,
            "projectId": <projectId>,
            "name": "Example Holdout",
            "key": "holdout-abcdefgh",
            "description": "Example holdout",
            "holdoutPercentage": 5,
            "evaluationMode": "remote",
            "bucketingKey": "amplitude_id",
            "bucketingSalt": "ABCDEFGH",
            "variantName": "on",
            "experiments": [123],
            "individualInclusion": ["x@amplitude.com"],
            "individualExclusion": ["y@amplitude.com"],
            "deleted": false,
            "createdBy": <createdBy>,
            "lastModifiedBy": <lastModifiedBy>,
            "createdAt": "2025-01-01T00:00:00.000Z",
            "lastModifiedAt": "2025-01-01T00:00:00.000Z"
        }
	],
    "nextCursor": <cursorId>
}
```
{% /code-group %}

## Get details

```bash
GET https://experiment.amplitude.com/api/1/holdouts/<id>
```

Fetch the configuration details of a holdout group.

### Path variables

| Name | Type   | Required | Description             |
| ---- | ------ | -------- | ----------------------- |
| `id` | String | Yes      | The holdout group's ID. |

### Response

A successful request returns a `200 OK` response and a JSON object with the holdout group's details.

{% code-group %}
```bash Request
curl --request GET \
    --url 'https://experiment.amplitude.com/api/1/holdouts/<id>' \
    --header 'Accept: application/json' \
    --header 'Authorization: Bearer <management-api-key>'
```

```bash Response
{
    "id": <holdoutId>,
    "projectId": <projectId>,
    "name": "Example Holdout",
    "key": "holdout-abcdefgh",
    "description": "Example holdout",
    "holdoutPercentage": 5,
    "evaluationMode": "remote",
    "bucketingKey": "amplitude_id",
    "bucketingSalt": "ABCDEFGH",
    "variantName": "on",
    "experiments": [123],
    "individualInclusion": ["x@amplitude.com"],
    "individualExclusion": ["y@amplitude.com"],
    "deleted": false,
    "createdBy": <createdBy>,
    "lastModifiedBy": <lastModifiedBy>,
    "createdAt": "2025-01-01T00:00:00.000Z",
    "lastModifiedAt": "2025-01-01T00:00:00.000Z"
}
```
{% /code-group %}

## Edit

```bash
PATCH https://experiment.amplitude.com/api/1/holdouts/{id}
```

Edit a holdout group.

### Path variables

| Name | Description                           |
| ---- | ------------------------------------- |
| `id` | Required. String. Holdout group's ID. |

### Request body

| Name                  | Type         | Required | Description                                                                                                                                          |
| --------------------- | ------------ | -------- | ---------------------------------------------------------------------------------------------------------------------------------------------------- |
| `name`                | String       | No       | The holdout group name.                                                                                                                              |
| `description`         | String       | No       | The holdout group description.                                                                                                                       |
| `experiments`         | Number array | No       | List of experiment IDs to include in this holdout group. Experiment evaluation mode must be compatible with the holdout group's evaluation mode.     |
| `individualInclusion` | String array | No       | List of user IDs or device IDs to include in this holdout group. Included users never experience the experiments.                                    |
| `individualExclusion` | String array | No       | List of user IDs or device IDs to exclude from this holdout group. Excluded users may experience the experiments.                                    |
| `archive`             | Boolean      | No       | Archives the holdout group. Setting this property marks the holdout 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",
  "experiments": [123],
  "individualInclusion": ["x@amplitude.com"]
}
```

{% /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/holdouts/<id>' \
    --header 'Content-Type: application/json' \
    --header 'Accept: application/json' \
    --header 'Authorization: Bearer <management-api-key>' \
    --data '{"name": "updated name"}'
```

{% /callout %}

## Create

```bash
POST https://experiment.amplitude.com/api/1/holdouts
```

Create a new holdout group.

### Request body

| Name                  | Type         | Required | Description                                                                                                                                      |
| --------------------- | ------------ | -------- | ------------------------------------------------------------------------------------------------------------------------------------------------ |
| `projectId`           | Number       | Yes      | Project ID of the holdout group.                                                                                                                 |
| `name`                | String       | Yes      | The holdout group name.                                                                                                                          |
| `key`                 | String       | No       | The holdout group key. Must be unique. If not specified, Amplitude generates a random key.                                                       |
| `description`         | String       | No       | The holdout group description.                                                                                                                   |
| `holdoutPercentage`   | Number       | Yes      | Holdout percentage. An integer between 1 and 99, inclusive.                                                                                      |
| `evaluationMode`      | String       | No       | Evaluation mode. Options are `local` and `remote`. Defaults to `remote`.                                                                         |
| `bucketingKey`        | String       | No       | Bucketing key. Defaults to `amplitude_id`.                                                                                                       |
| `experiments`         | Number array | No       | List of experiment IDs to include in this holdout group. Experiment evaluation mode must be compatible with the holdout group's evaluation mode. |
| `individualInclusion` | String array | No       | List of user IDs or device IDs to include in this holdout group. Included users never experience the experiments.                                |
| `individualExclusion` | String array | No       | List of user IDs or device IDs to exclude from this holdout group. Excluded users may experience the experiments.                                |

{% callout type="example" heading="Example request" %}

```json
{
    "projectId": <projectId>,
    "name": "Example Holdout",
  	"key": "example-holdout",
    "holdoutPercentage": 5,
    "evaluationMode": "local",
    "bucketingKey": "device_id",
    "experiments": [21197],
    "individualInclusion": ["x@amplitude.com"],
    "individualExclusion": ["y@amplitude.com"],
}
```

{% /callout %}

### Response

A successful request returns a `200 OK` response and a JSON object with the holdout group's ID and URL.

{% code-group %}
```bash Request
curl --request POST \
    --url 'https://experiment.amplitude.com/api/1/holdouts' \
    --header 'Content-Type: application/json' \
    --header 'Accept: application/json' \
    --header 'Authorization: Bearer <management-api-key>' \
    --data '{"projectId":"<projectId>","name":"Example Holdout","holdoutPercentage":5}'
```

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