Create a new Holdout

1 min

POST

https://api.optimizely.com/flags/v1//projects/{project_id}/holdouts

Creates a new holdout experiment to establish a control group for measuring the impact of your feature flags and experiments.

A holdout reserves a percentage of your traffic (specified in basis points) that will be excluded from seeing any experiments, allowing you to measure the overall impact of your experimentation program against a baseline control group.

The holdout will be created in a draft status and can be configured with:

Traffic allocation: Percentage of users to exclude from experiments (0-10000 basis points)
Scope: Global (affects all experiments) or local (specific experiments only)
Audiences: Target specific user segments using audience conditions
Metrics: Track and analyze the impact on key business metrics
Environment: Specify which environment the holdout applies to

Key Validation Rules:

Holdout key must be unique within the project
Required fields: key, name
traffic_allocation must be between 0-10000 (basis points)
key must match pattern: ^[a-zA-Z0-9_\-]+$ (max 64 characters)
name and description have character limits (255 and 1000 respectively)

Metrics Integration: If metrics are provided, they will be automatically saved to the MetricsHub for tracking and analysis.

project_idintegerThe project identifier

acceptstringGenerated from available response content types

bodyobjectRequest body schema for creating or updating a holdout. Holdouts are experiments that reserve a portion of your traffic to measure the impact of your feature flags and experiments. They help establish a control group by excluding a percentage of users from seeing any experiments, allowing you to measure the overall impact of your experimentation program.

201Successful retrieval, creation or update of a Holdout. The response includes RESTful JSON (<a href="https://restfuljson.org/" target="_blank">https://restfuljson.org/</a>) styled links. If a link is not present in the response, it indicates a user is not authorized to access the related resource.

400Bad Request - Invalid input data or validation failure. Common causes: <ul> <li>Missing required fields (<code>key</code> or <code>name</code>)</li> <li>Duplicate holdout key within the project</li> <li>Invalid <code>key</code> format (must be alphanumeric with underscores/hyphens only)</li> <li><code>traffic_allocation</code> outside valid range (0-10000)</li> <li>Field length limits exceeded</li> <li>Invalid JSON structure in request body</li> <li>Malformed audience conditions or metrics configuration</li> </ul>

401Invalid credentials

403Do not have permission to perform the operation

curl --request POST \
     --url https://api.optimizely.com/flags/v1//projects/{project_id}/holdouts \
     --header 'accept: application/json' \
     --header 'content-type: application/json' \
     --data '{
     "key": "annual_growth_holdout",
     "metrics": [
     {
     "aggregator": "",
     "event_properties": {
     "filter": {
     "conditions": [
     {
     "name": "",
     "operator": "",
     "type": "",
     "value": ""
     }
     ]
     }
     },
     "winning_direction": ""
     }
     ],
     "name": "Annual Growth Control Group",
     "scope": "global",
     "scope_type": "exclude"
     }'