Create a cross-project Holdout

1 min

POST

https://api.optimizely.com/flags/v1//holdouts

Creates a new holdout via a project-agnostic endpoint. Supports both global (applies to all rules in selected projects) and local (applies to specific rules) scopes. This endpoint does not require a project_id in the URL — the client provides project_id in the request body.

Required field: project_id — The ID of the project that owns this holdout. Used for database unique constraints and permission inheritance.

Global holdouts:

Provide project_ids — the holdout applies to ALL rules in the specified projects.
The project_id must be one of the project_ids.

Local holdouts:

Provide rule_ids — the holdout applies to ONLY the specified rules.
The project_ids are auto-derived from each rule's flag ownership. Not required — will be ignored if provided.
The project_id must be the owner of at least one of the rule_ids.

Gated behind the holdouts-m2 feature flag.

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. NOTE: This schema is shared between two endpoints with different validation rules: <ul> <li>POST /projects/{project_id}/holdouts: <code>project_id</code>, <code>project_ids</code>, and <code>rule_ids</code> from the body are ignored (project comes from URL)</li> <li>POST /holdouts: <code>project_id</code> is required in the body, plus either <code>project_ids</code> (global) or <code>rule_ids</code> (local)</li> </ul> These constraints are enforced at runtime by the API, not by OpenAPI schema validation.

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 <code>project_id</code> (required for cross-project creates)</li> <li>Global scope: <code>project_id</code> not in <code>project_ids</code></li> <li>Local scope: <code>project_id</code> doesn't own any of the specified <code>rule_ids</code></li> <li>Global holdout missing <code>project_ids</code></li> <li>Local holdout missing <code>rule_ids</code></li> <li>Global holdout with <code>rule_ids</code> (not allowed)</li> <li>Invalid scope value</li> <li>Duplicate holdout key</li> <li>Rule not found</li> <li><code>audience_conditions</code> set on a holdout whose targeted rules span more than one project</li> </ul>

401Invalid credentials

403Do not have permission to perform the operation

curl --request POST \
     --url https://api.optimizely.com/flags/v1//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"
     }'