Model: HoldoutRequestBody

1 min

Model Parameters

HoldoutRequestBody
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
}
```
- archivedboolean
  Description
  Whether the holdout is archived. New holdouts are created as unarchived by default.
- audience_conditionsobject[]
  Example
  ["["or",{"audience_id":5340810295},{"audience_id":1234567890}]"]
  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.
- created_by_user_emailstring
  Example
  [email protected]
  Description
  Email of the user who created the holdout.
- created_timestring<date-time>
  Example
  2024-01-01T10:00:00.000Z
  Description
  Timestamp when the holdout was 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.
  Format
  date-time
- 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
- idinteger
  Example
  12345
  Description
  System-generated unique identifier for the holdout.
- 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.
- revisioninteger
  Example
  1
  Description
  Revision number for tracking changes to the holdout.
- 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
- statusstring<draft | running | concluded>
  Example
  draft
  Description
  Current status of the holdout.
  Allowed
  draftrunningconcluded
- 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
- updated_timestring<date-time>
  Example
  2024-01-01T10:00:00.000Z
  Description
  Timestamp when the holdout was last updated.
  Format
  date-time

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