---
title: Experiment Management API Holdout Group Endpoints
description: 
product: experiment
token_estimate: 1843
---
# 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 of holdout groups including their configuration details. |
| [Edit](#edit) | Edit holdout group. |
| [Create](#create) | Create a new holdout. |

## List

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

Fetch a list of holdout groups including their configuration details.

### Query parameters

| Name | Description |
| --- | --- |
| `limit` | The maximum number of mutex groups to return. Capped at 1000. |
| `cursor` | The offset that starts the page of results. |

### 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 | Description |
| --- | --- |
| `id` | Required. String. 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 | Required | Type | Description |
| --- | --- | --- | --- |
| `name` | Optional | `string` | The holdout group name. |
| `description` | Optional | `string` | The holdout group description. |
| `experiments` | Optional | `number array` | List of experiment IDs to include in this holdout group. The experiment evaluation mode must be compatible with the holdout group's evaluation mode. |
| `individualInclusion` | Optional | `string array` | List of user IDs or device IDs to include in this holdout group. Included users never experience the experiments. |
| `individualExclusion` | Optional | `string array` | List of user IDs or device IDs to exclude from this holdout group. Excluded users may experience the experiments. |
| `archive` | Optional | `boolean` | Archives or unarchives the holdout group. When archived, the holdout group is set as deleted and removed 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 | Required | Type | Description |
| --- | --- | --- | --- |
| `projectId` | Required | `number` | Project ID of the holdout group. |
| `name` | Required | `string` | The holdout group name. |
| `key` | Optional | `string` | The holdout group key. Must be unique across all flags, experiments, holdout groups, and mutex groups. Amplitude generates a key if you don't specify one. |
| `description` | Optional | `string` | The holdout group description. |
| `holdoutPercentage` | Required | `number` | Holdout percentage. An integer between 1 and 99 inclusive. |
| `evaluationMode` | Optional | `string` | Evaluation mode. Options are `local` and `remote`. Defaults to `remote`. |
| `bucketingKey` | Optional | `string` | Bucketing key. Defaults to `amplitude_id`. |
| `experiments` | Optional | `number array` | List of experiment IDs to include in this holdout group. The experiment evaluation mode must be compatible with the holdout group's evaluation mode. |
| `individualInclusion` | Optional | `string array` | List of user IDs or device IDs to include in this holdout group. Included users never experience the experiments. |
| `individualExclusion` | Optional | `string array` | 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"
}
```