Experiment Management API Holdout Group Endpoints

Name	Description
List	List holdout groups with their configuration details.
Get details	Get the configuration details of a holdout group.
Edit	Edit a holdout group.
Create	Create a new holdout group.

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.

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.

bash

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

bash

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

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

Was this helpful?