Create a new Holdout

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.

Recent Requests

Time	Status	User Agent
Retrieving recent requests…

Loading…

Path Params

project_id

integer

required

The project identifier

Body Params

audience_conditions

array

Defines which audiences this holdout should apply to. If omitted, the holdout applies to all users. Uses the same structure as audience conditions in experiments - supports logical operators like 'and', 'or', 'not'.

audience_conditions

audience_ids

array of integers

deprecated

DEPRECATED: Use audience_conditions instead. List of audience IDs that this holdout should apply to. This field is maintained for backward compatibility.

audience_ids

description

string

length ≤ 1000

Optional detailed description explaining the purpose and context of this holdout. Helps team members understand what this holdout is measuring.

environment_key

string

The environment where this holdout will be active (e.g., 'production', 'staging'). The holdout will only affect traffic in this specific environment.

key

string

required

length ≤ 64

Unique identifier for the holdout. Must be unique within the project. Use alphanumeric characters, underscores, and hyphens only.

metrics

array of objects

List of metrics that will be tracked and analyzed for this holdout. These metrics help measure the impact of experiments on your control group.

metrics

name

string

required

length ≤ 255

Human-readable name for the holdout that will be displayed in the UI.

scope

string

enum

Defaults to global

Defines the scope of the holdout:

'global': Affects all experiments across the entire project
'local': Affects only specific experiments or flags (requires additional configuration)

Allowed:

scope_type

string

enum

Defaults to exclude

Defines how the holdout scope is applied:

'exclude': Users in holdout are excluded from seeing experiments (most common)
'include': Users in holdout are included in experiments (less common)

Allowed:

start_time

date-time

When the holdout should become active. If not specified, the holdout will be active immediately upon creation. Must be in ISO 8601 format.

traffic_allocation

integer

0 to 10000

Percentage of traffic to allocate to this holdout, expressed in basis points (1/100th of a percent). For example: 100 = 1%, 1000 = 10%, 5000 = 50%. The remaining traffic will see experiments normally.

Headers

string

enum

Defaults to application/json

Generated from available response content types

Allowed:

Responses

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

401Invalid credentials

403Do not have permission to perform the operation