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

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.

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

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.

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

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 request

json

{
    "name": "updated name",
    "description": "updated description",
  	"experiments": [123],
  	"individualInclusion": ["x@amplitude.com"]
}

Response

A successful request returns a 200 OK response.

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

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

Was this helpful?