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 for tracking and analysis.

Path Parameters

project_idintegerrequired
Example
12345
Description
The project identifier

Body Parameters

bodyHoldoutRequestBodyrequired
Example
```
{
  "audience_conditions": [
    "or",
    {
      "audience_id": 5340810295
    }
  ],
  "description": "Holdout group to measure the overall impact of our growth experiments throughout the year",
  "environment_key": "production",
  "key": "annual_growth_holdout",
  "metrics": [
    {
      "aggregator": "unique",
      "display_title": "Conversion Rate",
      "scope": "visitor",
      "winning_direction": "increasing"
    }
  ],
  "name": "Annual Growth Control Group",
  "project_id": 12345,
  "project_ids": [
    12345,
    67890
  ],
  "scope": "global",
  "start_time": "2024-01-01T00:00:00.000Z",
  "traffic_allocation": 500
}
```
Description
Request 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:
- POST /projects/{project_id}/holdouts: project_id, project_ids, and rule_ids from the body are ignored (project comes from URL)
- POST /holdouts: project_id is required in the body, plus either project_ids (global) or rule_ids (local)
These constraints are enforced at runtime by the API, not by OpenAPI schema validation.
- audience_conditionsobject[]
  Description
  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_idsinteger[]
  Example
```
[
  5340810295,
  1234567890
]
```
  Description
  Warning: Deprecated
  DEPRECATED: Use audience_conditions instead. List of audience IDs that this holdout should apply to. This field is maintained for backward compatibility.
- descriptionstring
  Example
  Holdout group to measure the overall impact of our growth experiments throughout the year
  Description
  Optional detailed description explaining the purpose and context of this holdout. Helps team members understand what this holdout is measuring.
  Max Length
  1000
- environment_keystring
  Example
  production
  Description
  The environment where this holdout will be active (e.g., 'production', 'staging'). The holdout will only affect traffic in this specific environment.
- exclude_targeted_deliveriesboolean
  Description
  When true, Targeted Delivery rules are excluded from this holdout, so holdout users are not withheld from them. Targeted Deliveries represent permanent ship decisions rather than active experiments, so there is nothing to measure by withholding them. Applies to global holdouts only; ignored for local holdouts. Can only be changed while the holdout is in draft status. Defaults to false.
  Default
  false
- keystringrequired
  Example
  annual_growth_holdout
  Description
  Unique identifier for the holdout. Must be unique within the project. Use alphanumeric characters, underscores, and hyphens only.
  Max Length
  64
  Pattern
  ^[a-zA-Z0-9_\-]+$
- metricsMetric[]
  Description
  List of metrics that will be tracked and analyzed for this holdout. These metrics help measure the impact of experiments on your control group.
  - aggregatorstring<unique | count | sum | ratio>required
    Description
    The aggregation function for the numerator of the metric. 'unique' measures the number of unique visitors/sessions that include the specified Event. 'count' measures the total number of occurrences of Event for the scope (visitor/session). 'sum' is the sum of the 'field' value
    Allowed
    uniquecountsumratio
  - display_titlestring
    Description
    An optional title for the unique metric configuration. If not provided, the event name will be used.
  - display_unitstring
    Description
    An optional name for the unit of the unique metric configuration.
  - event_idinteger<int64>
    Example
    32334454244
    Description
    The ID for the Event to select data from. Omitted for global metrics that are not relative to a specific Event, i.e. "overall revenue"
    Format
    int64
  - event_propertiesobject
    - filterobject
      - combine_operatorstring<or | and>
        Allowed
        orand
      - conditionsEventPropertyCondition[]
        namestringrequired
        operatorstring<equal_to | not_equal_to | greater_than | greater_than_or_equal_to | less_than | less_than_or_equal_to | contains | does_not_contain>required
        Allowed
        equal_tonot_equal_togreater_thangreater_than_or_equal_toless_thanless_than_or_equal_tocontainsdoes_not_contain
        typestring<string | number | boolean>required
        Allowed
        stringnumberboolean
        valuestringrequired
  - event_typestring
  - fieldstring<revenue | value>
    Description
    The field to aggregate for the numerator of the metric. Required when 'aggregator' = 'sum', otherwise omitted
    Allowed
    revenuevalue
  - idstring
    Description
    A unique identifier for the metric configuration.
  - metricsSubMetric[]
    - aggregatorstring
    - display_titlestring
    - event_idinteger
    - event_typestring
    - fieldstring
    - rolestring<numerator | denominator>
      Allowed
      numeratordenominator
    - scopestring
  - project_idinteger
    Description
    A unique identifier for the project associated with the metric.
  - scopestring<session | visitor | event>
    Description
    Specifies how Events should be grouped together. Can also be thought of as the denonimator of the metric. 'session' divides by the number of sessions. "Influenced sessions", or sessions that do not contain a decision Event but carry a decision from a previous session are not included in counts for numerator or denominator. 'visitor' divides by the number of visitors. 'event' divides by the total occurrences (impressions) of the specified Event
    Allowed
    sessionvisitorevent
  - visibilitystring<account | experiment | project>
    Description
    The visibility of the metric.
    Allowed
    accountexperimentproject
  - winning_directionstring<increasing | decreasing>required
    Description
    The winning direction of this metric
    Allowed
    increasingdecreasing
- namestringrequired
  Example
  Annual Growth Control Group
  Description
  Human-readable name for the holdout that will be displayed in the UI.
  Max Length
  255
- project_idinteger<int64>
  Example
  12345
  Description
  The ID of the project that owns this holdout.
  
  For POST /holdouts (cross-project creates) - required, validated at runtime:
  
  Global scope: Must be one of the project_ids in the request.
  
  Local scope: Must be the project ID that owns at least one of the specified rule_ids.
  
  Returns 400 if missing or invalid.
  
  For POST /projects/{project_id}/holdouts (project-scoped creates): Ignored in the request body. The project_id comes from the URL path parameter.
  
  In responses: Always present. Indicates which project owns the holdout.
  
  Used for:
  
  Database unique constraint on (key, project_id)
  
  Permission inheritance
  Format
  int64
- project_idsinteger[]
  Example
```
[
  12345,
  67890
]
```
  Description
  List of project IDs that this holdout applies to.
  
  For POST /holdouts (cross-project):
  
  Global scope: Required (validated at runtime). Specifies which projects the holdout affects.
  
  Local scope: Ignored. Projects are auto-derived from rule_ids.
  
  For POST /projects/{project_id}/holdouts (project-scoped):
  
  Ignored. The project comes from the URL path parameter.
- rule_idsinteger[]
  Example
```
[
  111,
  222
]
```
  Description
  List of rule IDs that this holdout applies to.
  
  For POST /holdouts (cross-project):
  
  Local scope: Required (validated at runtime). Specifies which rules the holdout affects.
  
  Global scope: Ignored. Mutually exclusive with global scope.
  
  For POST /projects/{project_id}/holdouts (project-scoped):
  
  Ignored. Only single-project holdouts are supported via this endpoint.
- scopestring<global | local>
  Example
  global
  Description
  Defines the scope of the holdout:
  
  'global': Affects all experiments across the entire project
  
  'local': Affects only specific experiments or flags (requires additional configuration)
  
  Defaults to 'global' when omitted (enforced at runtime, not by OpenAPI schema validation).
  
  For POST /projects/{project_id}/holdouts (project-scoped):
  
  Only 'global' is supported. 'local' is rejected with a 400 error, because this endpoint ignores rule_ids and a local-scope holdout cannot be targeted here. Use the cross-project endpoint (POST /holdouts) with rule_ids to create a local-scope holdout.
  Default
  global
  Allowed
  globallocal
- start_timestring<date-time>
  Example
  2024-01-01T00:00:00.000Z
  Description
  When the holdout should become active. If not specified, the holdout will be active immediately upon creation. Must be in ISO 8601 format.
  Format
  date-time
- traffic_allocationinteger
  Example
  1000
  Description
  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.
  Minimum
  0
  Maximum
  10000

Responses

201

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

Holdout
Example
```
{
  "archived": false,
  "audience_conditions": [
    "or",
    {
      "audience_id": 5340810295
    }
  ],
  "created_by_user_email": "[email protected]",
  "created_time": "2023-12-15T10:00:00.000Z",
  "description": "Holdout group to measure the overall impact of our growth experiments throughout the year",
  "environment_key": "production",
  "holdout_results_api_token": "SampleToken.eyJhbGciOiJIUzI1NiIsInR5cCI6IkpXVCJ9",
  "id": 12345,
  "key": "annual_growth_holdout",
  "metrics": [
    {
      "aggregator": "unique",
      "display_title": "Conversion Rate",
      "scope": "visitor",
      "winning_direction": "increasing"
    }
  ],
  "name": "Annual Growth Control Group",
  "project_id": 98765,
  "revision": 3,
  "scope": "global",
  "start_time": "2024-01-01T00:00:00.000Z",
  "status": "running",
  "traffic_allocation": 1000,
  "updated_time": "2024-01-01T10:00:00.000Z",
  "urn": "holdout.flag.optimizely.com::12345"
}
```
Description
Represents a holdout experiment that reserves a portion of traffic to measure the impact of feature flags and experiments.

Holdouts help establish control groups by excluding a percentage of users from seeing any experiments, allowing you to measure the overall impact of your experimentation program against a baseline.
- archivedboolean
  Description
  Whether the holdout is archived. Archived holdouts are hidden from normal views but retain their historical data and configuration.
- audience_conditionsobject[]
  Example
  ["["or",{"audience_id":5340810295},{"audience_id":1234567890}]"]
  Description
  Defines which audiences this holdout applies to. If omitted, the holdout applies to all users. Uses logical operators like 'and', 'or', 'not' to combine multiple audience conditions.
- audience_idsinteger[]
  Example
```
[
  5340810295,
  1234567890
]
```
  Description
  Warning: Deprecated
  DEPRECATED: Use audience_conditions instead. List of audience IDs that this holdout applies to. This field is maintained for backward compatibility.
- created_by_user_emailstring
  Example
  [email protected]
  Description
  Email address of the user who created the holdout.
- created_timestring<date-time>
  Example
  2023-12-15T10:00:00.000Z
  Description
  Timestamp when the holdout was originally created.
  Format
  date-time
- descriptionstring
  Example
  Holdout group to measure the overall impact of our growth experiments throughout the year
  Description
  Optional detailed description explaining the purpose and context of this holdout. Helps team members understand what this holdout is measuring.
  Max Length
  1000
- end_timestring<date-time>
  Example
  2024-12-31T23:59:59.000Z
  Description
  Timestamp when the holdout finished or will finish. Null for holdouts that are still running or have no defined end time.
  Format
  date-time
- environment_keystring
  Example
  production
  Description
  The environment where this holdout is active (e.g., 'production', 'staging'). The holdout only affects traffic in this specific environment.
- environment_namestring
  Example
  Production
  Description
  The human-readable name of the environment where this holdout is active.
- exclude_targeted_deliveriesboolean
  Description
  When true, Targeted Delivery rules are excluded from this holdout, so holdout users are not withheld from them. Targeted Deliveries represent permanent ship decisions rather than active experiments, so there is nothing to measure by withholding them. Applies to global holdouts only; ignored for local holdouts. Can only be changed while the holdout is in draft status. Defaults to false.
  Default
  false
- holdout_results_api_tokenstring
  Example
  SampleToken.eyJhbGciOiJIUzI1NiIsInR5cCI6IkpXVCJ9
  Description
  API token for accessing holdout results and analytics data. This token is dynamically generated for each API response and provides secure access to holdout-specific results endpoints.
- idintegerrequired
  Example
  12345
  Description
  System-generated unique identifier for the holdout.
- keystringrequired
  Example
  annual_growth_holdout
  Description
  Unique user-defined identifier for the holdout within the project. Must contain only alphanumeric characters, underscores, and hyphens.
  Max Length
  64
  Pattern
  ^[a-zA-Z0-9_\-]+$
- metricsMetric[]
  Description
  List of metrics being tracked and analyzed for this holdout. These metrics help measure the impact of experiments on the control group.
  - aggregatorstring<unique | count | sum | ratio>required
    Description
    The aggregation function for the numerator of the metric. 'unique' measures the number of unique visitors/sessions that include the specified Event. 'count' measures the total number of occurrences of Event for the scope (visitor/session). 'sum' is the sum of the 'field' value
    Allowed
    uniquecountsumratio
  - display_titlestring
    Description
    An optional title for the unique metric configuration. If not provided, the event name will be used.
  - display_unitstring
    Description
    An optional name for the unit of the unique metric configuration.
  - event_idinteger<int64>
    Example
    32334454244
    Description
    The ID for the Event to select data from. Omitted for global metrics that are not relative to a specific Event, i.e. "overall revenue"
    Format
    int64
  - event_propertiesobject
    - filterobject
      - combine_operatorstring<or | and>
        Allowed
        orand
      - conditionsEventPropertyCondition[]
        namestringrequired
        operatorstring<equal_to | not_equal_to | greater_than | greater_than_or_equal_to | less_than | less_than_or_equal_to | contains | does_not_contain>required
        Allowed
        equal_tonot_equal_togreater_thangreater_than_or_equal_toless_thanless_than_or_equal_tocontainsdoes_not_contain
        typestring<string | number | boolean>required
        Allowed
        stringnumberboolean
        valuestringrequired
  - event_typestring
  - fieldstring<revenue | value>
    Description
    The field to aggregate for the numerator of the metric. Required when 'aggregator' = 'sum', otherwise omitted
    Allowed
    revenuevalue
  - idstring
    Description
    A unique identifier for the metric configuration.
  - metricsSubMetric[]
    - aggregatorstring
    - display_titlestring
    - event_idinteger
    - event_typestring
    - fieldstring
    - rolestring<numerator | denominator>
      Allowed
      numeratordenominator
    - scopestring
  - project_idinteger
    Description
    A unique identifier for the project associated with the metric.
  - scopestring<session | visitor | event>
    Description
    Specifies how Events should be grouped together. Can also be thought of as the denonimator of the metric. 'session' divides by the number of sessions. "Influenced sessions", or sessions that do not contain a decision Event but carry a decision from a previous session are not included in counts for numerator or denominator. 'visitor' divides by the number of visitors. 'event' divides by the total occurrences (impressions) of the specified Event
    Allowed
    sessionvisitorevent
  - visibilitystring<account | experiment | project>
    Description
    The visibility of the metric.
    Allowed
    accountexperimentproject
  - winning_directionstring<increasing | decreasing>required
    Description
    The winning direction of this metric
    Allowed
    increasingdecreasing
- namestringrequired
  Example
  Annual Growth Control Group
  Description
  Human-readable name for the holdout displayed in the UI.
  Max Length
  255
- project_idinteger<int64>
  Example
  98765
  Description
  The unique identifier of the project this holdout belongs to.
  Format
  int64
- projectsobject[]
  Example
```
[
  {
    "id": 123
  }
]
```
  Description
  Project objects returned by cross-project GET endpoints. For global-scope holdouts, lists target project IDs. Empty array for local-scope holdouts. Frontend resolves project names via entity-management API.
  - idinteger<int64>
    Description
    Project ID.
    Format
    int64
- revisioninteger
  Example
  3
  Description
  Revision number that increments with each change to the holdout. Used for tracking modifications and ensuring data consistency.
- rulesobject[]
  Example
```
[
  {
    "flag_key": "my_flag",
    "id": 456,
    "key": "experiment_rule_a",
    "name": "Experiment Rule A",
    "project_id": 123
  }
]
```
  Description
  Enriched rule objects returned by cross-project GET endpoints. For local-scope holdouts, lists target rules with metadata. Empty array for global-scope holdouts.
  - flag_idinteger<int64>
    Description
    ID of the flag containing this rule.
    Format
    int64
  - flag_keystring
    Description
    Key of the flag containing this rule.
  - flag_namestring
    Description
    Name of the flag containing this rule.
  - idinteger<int64>
    Description
    Rule ID.
    Format
    int64
  - keystring
    Description
    Rule key.
  - namestring
    Description
    Rule name.
  - project_idinteger<int64>
    Description
    ID of the project this rule belongs to.
    Format
    int64
- scopestring<global | local>
  Example
  global
  Description
  Defines the scope of the holdout:
  
  'global': Affects all experiments across the entire project
  
  'local': Affects only specific experiments or flags
  Allowed
  globallocal
- start_timestring<date-time>
  Example
  2024-01-01T00:00:00.000Z
  Description
  Timestamp when the holdout became or will become active. When the holdout starts affecting traffic allocation.
  Format
  date-time
- statusstring<draft | running | concluded>
  Example
  running
  Description
  Current operational status of the holdout:
  
  'draft': Holdout is configured but not yet active
  
  'running': Holdout is currently active and affecting traffic
  
  'concluded': Holdout has finished and is no longer active
  Allowed
  draftrunningconcluded
- traffic_allocationinteger
  Example
  1000
  Description
  Percentage of traffic allocated to this holdout, expressed in basis points (1/100th of a percent). For example: 100 = 1%, 1000 = 10%, 5000 = 50%. The remaining traffic sees experiments normally.
  Minimum
  0
  Maximum
  10000
- updated_timestring<date-time>
  Example
  2024-01-01T10:00:00.000Z
  Description
  Timestamp when the holdout was last modified.
  Format
  date-time
- urlstring
  Example
  /holdouts/12345
  Description
  RESTful link to fetch this holdout's details. For project-scoped endpoints: /projects/{project_id}/holdouts/{holdout_id} For cross-project endpoints: /holdouts/{holdout_id}
- urnstring
  Example
  holdout.flag.optimizely.com::12345
  Description
  Universal Resource Name (URN) for the holdout, used for global identification.

400

Bad Request - Invalid input data or validation failure.

Common causes:

Missing required fields (key or name)
Duplicate holdout key within the project
Invalid key format (must be alphanumeric with underscores/hyphens only)
traffic_allocation outside valid range (0-10000)
Field length limits exceeded
Invalid JSON structure in request body
Malformed audience conditions or metrics configuration

ProblemDetail
Examples
Duplicate holdout key:
{ "detail": "Another entity already exists with the key 'checkout_holdout'.", "status": 400, "title": "Key checkout_holdout already exists", "type": "about:blank" }
Invalid request data:
{ "detail": "traffic_allocation must be between 0 and 10000", "status": 400, "title": "Invalid request data", "type": "about:blank" }
Description
https://tools.ietf.org/html/rfc7807#section-3.1
- detailstringrequired
  Description
  A human-readable explanation specific to this occurrence of the problem.
- statusintegerrequired
  Description
  The HTTP status code ([RFC7231], Section 6) generated by the origin server for this occurrence of the problem.
- titlestringrequired
  Description
  A short, human-readable summary of the problem type.
- typestringrequired
  Description
  A URI reference [RFC3986] that identifies the problem type. Contains 'about
  ' if unspecified.
- uuidstring
  Description
  Error reference for customer support

401Invalid credentials

403Do not have permission to perform the operation

curl

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

javascript

var myHeaders = new Headers();
myHeaders.append("accept", "application/json");
myHeaders.append("content-type", "application/json");

var raw = JSON.stringify({
   "key": "annual_growth_holdout",
   "metrics": [
      {
         "aggregator": "",
         "event_properties": {
            "filter": {
               "conditions": [
                  {
                     "name": "",
                     "operator": "",
                     "type": "",
                     "value": ""
                  }
               ]
            }
         },
         "winning_direction": ""
      }
   ],
   "name": "Annual Growth Control Group",
   "scope": "global"
});

var requestOptions = {
   method: 'POST',
   headers: myHeaders,
   body: raw,
   redirect: 'follow'
};

fetch("https://api.optimizely.com/flags/v1//projects/{project_id}/holdouts", requestOptions)
   .then(response => response.text())
   .then(result => console.log(result))
   .catch(error => console.log('error', error));

ruby

require "uri"
require "json"
require "net/http"

url = URI("https://api.optimizely.com/flags/v1//projects/{project_id}/holdouts")

https = Net::HTTP.new(url.host, url.port)
https.use_ssl = true

request = Net::HTTP::Post.new(url)
request["accept"] = "application/json"
request["content-type"] = "application/json"
request.body = JSON.dump({
   "key": "annual_growth_holdout",
   "metrics": [
      {
         "aggregator": "",
         "event_properties": {
            "filter": {
               "conditions": [
                  {
                     "name": "",
                     "operator": "",
                     "type": "",
                     "value": ""
                  }
               ]
            }
         },
         "winning_direction": ""
      }
   ],
   "name": "Annual Growth Control Group",
   "scope": "global"
})

response = https.request(request)
puts response.read_body

python

import requests
import json

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

payload = json.dumps({
   "key": "annual_growth_holdout",
   "metrics": [
      {
         "aggregator": "",
         "event_properties": {
            "filter": {
               "conditions": [
                  {
                     "name": "",
                     "operator": "",
                     "type": "",
                     "value": ""
                  }
               ]
            }
         },
         "winning_direction": ""
      }
   ],
   "name": "Annual Growth Control Group",
   "scope": "global"
})
headers = {
   'accept': 'application/json',
   'content-type': 'application/json'
}

response = requests.request("POST", url, headers=headers, data=payload)

print(response.text)

201

// Successful 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.
{
  "archived": false,
  "audience_conditions": [
    {}
  ],
  "audience_ids": [
    0
  ],
  "created_by_user_email": "[email protected]",
  "created_time": "2023-12-15T10:00:00.000Z",
  "description": "Holdout group to measure the overall impact of our growth experiments throughout the year",
  "end_time": "2024-12-31T23:59:59.000Z",
  "environment_key": "production",
  "environment_name": "Production",
  "exclude_targeted_deliveries": false,
  "holdout_results_api_token": "SampleToken.eyJhbGciOiJIUzI1NiIsInR5cCI6IkpXVCJ9",
  "id": 12345,
  "key": "annual_growth_holdout",
  "metrics": [
    {
      "aggregator": "",
      "display_title": "",
      "display_unit": "",
      "event_id": 32334454244,
      "event_properties": {
        "filter": {
          "combine_operator": "",
          "conditions": [
            {
              "name": "",
              "operator": "",
              "type": "",
              "value": ""
            }
          ]
        }
      },
      "event_type": "",
      "field": "",
      "id": "",
      "metrics": [
        {
          "aggregator": "",
          "display_title": "",
          "event_id": 0,
          "event_type": "",
          "field": "",
          "role": "",
          "scope": ""
        }
      ],
      "project_id": 0,
      "scope": "",
      "visibility": "",
      "winning_direction": ""
    }
  ],
  "name": "Annual Growth Control Group",
  "project_id": 98765,
  "projects": [
    {
      "id": ""
    }
  ],
  "revision": 3,
  "rules": [
    {
      "flag_id": "",
      "flag_key": "",
      "flag_name": "",
      "id": "",
      "key": "",
      "name": "",
      "project_id": ""
    }
  ],
  "scope": "global",
  "start_time": "2024-01-01T00:00:00.000Z",
  "status": "running",
  "traffic_allocation": 1000,
  "updated_time": "2024-01-01T10:00:00.000Z",
  "url": "/holdouts/12345",
  "urn": "holdout.flag.optimizely.com::12345"
}

400

// Bad Request - Invalid input data or validation failure.
Common causes:

Missing required fields (key or name)
Duplicate holdout key within the project
Invalid key format (must be alphanumeric with underscores/hyphens only)
traffic_allocation outside valid range (0-10000)
Field length limits exceeded
Invalid JSON structure in request body
Malformed audience conditions or metrics configuration
{
  "detail": "",
  "status": 0,
  "title": "",
  "type": "",
  "uuid": ""
}

GENERATED

// Bad Request - Invalid input data or validation failure.
Common causes:

Missing required fields (key or name)
Duplicate holdout key within the project
Invalid key format (must be alphanumeric with underscores/hyphens only)
traffic_allocation outside valid range (0-10000)
Field length limits exceeded
Invalid JSON structure in request body
Malformed audience conditions or metrics configuration
{
  "detail": "",
  "status": 0,
  "title": "",
  "type": "",
  "uuid": ""
}

duplicate_key

// Duplicate holdout key
{
  "detail": "Another entity already exists with the key 'checkout_holdout'.",
  "status": 400,
  "title": "Key checkout_holdout already exists",
  "type": "about:blank"
}

invalid_data

// Invalid request data
{
  "detail": "traffic_allocation must be between 0 and 10000",
  "status": 400,
  "title": "Invalid request data",
  "type": "about:blank"
}

401

// Invalid credentials

403

// Do not have permission to perform the operation