# Experiment Management API Holdout 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 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. |

> **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

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

#### Request

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

#### Response

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

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

#### Request

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

#### Response

```bash
{
    "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"
}
```

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

> **Example:** Example request
>
> ```json
> {
>   "name": "updated name",
>   "description": "updated description",
>   "experiments": [123],
>   "individualInclusion": ["x@amplitude.com"]
> }
> ```

### Response

A successful request returns a `200 OK` response.

> **Example:** 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"}'
> ```

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

> **Example:** 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"],
> }
> ```

### Response

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

#### Request

```bash
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}'
```

#### Response

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