Experiment Management API Holdout Group Endpoints

Name	Description
List	List of holdout groups including their configuration details.
Edit	Edit holdout group.
Create	Create a new holdout.

List

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

Fetch a list of holdout 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 holdout groups encoded as JSON in the response body.

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

 1{
 2      "holdouts": [
 3          {
 4            "id": <holdoutId>,
 5            "projectId": <projectId>,
 6            "name": "Example Holdout",
 7            "key": "holdout-abcdefgh",
 8            "description": "Example holdout",
 9            "holdoutPercentage": 5,
10            "evaluationMode": "remote",
11            "bucketingKey": "amplitude_id",
12            "bucketingSalt": "ABCDEFGH",
13            "variantName": "on",
14            "experiments": [123],
15            "individualInclusion": ["x@amplitude.com"],
16            "individualExclusion": ["y@amplitude.com"],
17            "deleted": false,
18            "createdBy": <createdBy>,
19            "lastModifiedBy": <lastModifiedBy>,
20            "createdAt": "2025-01-01T00:00:00.000Z",
21            "lastModifiedAt": "2025-01-01T00:00:00.000Z"
22        }
23    ],
24    "nextCursor": <cursorId>
25}

Get details

1GET 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.

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

 1{
 2    "id": <holdoutId>,
 3    "projectId": <projectId>,
 4    "name": "Example Holdout",
 5    "key": "holdout-abcdefgh",
 6    "description": "Example holdout",
 7    "holdoutPercentage": 5,
 8    "evaluationMode": "remote",
 9    "bucketingKey": "amplitude_id",
10    "bucketingSalt": "ABCDEFGH",
11    "variantName": "on",
12    "experiments": [123],
13    "individualInclusion": ["x@amplitude.com"],
14    "individualExclusion": ["y@amplitude.com"],
15    "deleted": false,
16    "createdBy": <createdBy>,
17    "lastModifiedBy": <lastModifiedBy>,
18    "createdAt": "2025-01-01T00:00:00.000Z",
19    "lastModifiedAt": "2025-01-01T00:00:00.000Z"
20}

Edit

1PATCH 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	Requirement	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 be included in this holdout group. Experiment evaluation mode must be compatible with holdout group's evaluation mode.
`individualInclusion`	Optional	string array	List of user ids or device ids to be included in this holdout group (never experience the experiments).
`individualExclusion`	Optional	string array	List of user ids or device ids to be excluded in this holdout group (may experience the experiments).
`archive`	Optional	boolean	Property to archive or unarchive holdout group. The holdout group will be set as deleted and removed from all child experiments’ parent dependencies.

Example request

1{
2    "name": "updated name",
3    "description": "updated description",
4      "experiments": [123],
5      "individualInclusion": ["x@amplitude.com"]
6}

Response

A successful request returns a 200 OK response.

Request

1curl --request PATCH \
2    --url 'https://experiment.amplitude.com/api/1/holdouts/<id>' \
3    --header 'Content-Type: application/json' \
4    --header 'Accept: application/json' \
5    --header 'Authorization: Bearer <management-api-key>' \
6    --data '{"name": "updated name"}'

Create

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

Create a new holdout group.

Request body

Name	Requirement	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. If not specified, one will be generated.
`description`	Optional	string	The holdout group description.
`holdoutPercentage`	Required	number	Holdout percentage. An integer number between 1 and 99 inclusively.
`evaluationMode`	Optional	string	Evaluation mode, options are `local` and `remote`. Defaulted to `remote`
`bucketingKey`	Optional	string	Bucketing key. Defaulted to "amplitude_id"
`experiments`	Optional	number array	List of experiment ids to be included in this holdout group. Experiment evaluation mode must be compatible with holdout group's evaluation mode.
`individualInclusion`	Optional	string array	List of user ids or device ids to be included in this holdout group (never experience the experiments).
`individualExclusion`	Optional	string array	List of user ids or device ids to be excluded in this holdout group (may experience the experiments).

Example request

 1{
 2    "projectId": <projectId>,
 3    "name": "Example Holdout",
 4      "key": "example-holdout",
 5    "holdoutPercentage": 5,
 6    "evaluationMode": "local",
 7    "bucketingKey": "device_id",
 8    "experiments": [21197],
 9    "individualInclusion": ["x@amplitude.com"],
10    "individualExclusion": ["y@amplitude.com"],
11}

Response

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

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

1{
2    "id": "<id>",
3    "url": "http://experiment.amplitude.com/amplitude/experiments/grouped-experiments"
4}