v5

latestOpenAPI 3.0.3Apache 2.0raw.githubusercontent.com2026-02-283466592.5 MB

Holdouts (beta)

Create holdout

Create a new holdout in the specified project.

post/api/v2/projects/{projectKey}/environments/{environmentKey}/holdouts

Path parameters

projectKeystring string required

The project key

environmentKeystring string required

The environment key

Request body

namestring

A human-friendly name for the holdout

keystring

A key that identifies the holdout

descriptionstring

Description of the holdout

randomizationunitstring

The chosen randomization unit for the holdout base experiment

attributesstring[]

The attributes that the holdout iteration's results can be sliced by

holdoutamountstring

Audience allocation for the holdout

primarymetrickeystring

The key of the primary metric for this holdout

prerequisiteflagkeystring

The key of the flag that the holdout is dependent on

maintainerIdstring

Maintainer id

Example request

{
  "name": "holdout-one-name",
  "key": "holdout-key",
  "description": "My holdout-one description",
  "randomizationunit": "user",
  "attributes": [
    "country",
    "device",
    "os"
  ],
  "holdoutamount": "10",
  "primarymetrickey": "metric-key-123abc",
  "metrics": [
    {
      "key": "metric-key-123abc",
      "isGroup": true,
      "primary": true
    }
  ],
  "prerequisiteflagkey": "flag-key-123abc"
}

Response

Holdout response

_idstring required

status'created' | 'enabled' | 'running' | 'ended' required

descriptionstring

holdoutAmountstring required

The percentage of traffic allocated to this holdout.

createdAtinteger required

updatedAtinteger required

Example response

{
  "baseExperiment": {
    "_id": "12ab3c45de678910fgh12345",
    "key": "experiment-key-123abc",
    "name": "Example experiment",
    "description": "An example experiment, used in testing",
    "_maintainerId": "12ab3c45de678910fgh12345",
    "tags": [
      "experiment",
      "feature"
    ],
    "_links": {
      "parent": {
        "href": "/api/v2/projects/my-project/environments/my-environment",
        "type": "application/json"
      },
      "self": {
        "href": "/api/v2/projects/my-project/environments/my-environment/experiments/my-experiment",
        "type": "application/json"
      }
    },
    "holdoutId": "f3b74309-d581-44e1-8a2b-bb2933b4fe40",
    "currentIteration": {
      "_id": "12ab3c45de678910fgh12345",
      "hypothesis": "The new button placement will increase conversion",
      "status": "running",
      "winningTreatmentId": "122c9f3e-da26-4321-ba68-e0fc02eced58",
      "winningReason": "We ran this iteration for two weeks and the winning variation was clear",
      "canReshuffleTraffic": true,
      "reallocationFrequencyMillis": 3600000,
      "primaryMetric": {
        "key": "metric-key-123abc",
        "name": "My metric",
        "kind": "custom",
        "isNumeric": true,
        "eventKey": "event-key-123abc",
        "_links": {
          "self": {
            "href": "/api/v2/metrics/my-project/my-metric",
            "type": "application/json"
          }
        },
        "metrics": [
          {
            "key": "metric-key-123abc",
            "_versionId": "version-id-123abc",
            "name": "Example metric",
            "kind": "custom",
            "isNumeric": true,
            "unitAggregationType": "sum",
            "eventKey": "event-key-123abc",
            "_links": {
              "self": {
                "href": "/api/v2/metrics/my-project/my-metric",
                "type": "application/json"
              }
            },
            "nameInGroup": "Step 1",
            "randomizationUnits": [
              "user"
            ]
          }
        ]
      },
      "primarySingleMetric": {
        "key": "metric-key-123abc",
        "_versionId": "version-id-123abc",
        "name": "Example metric",
        "kind": "custom",
        "isNumeric": true,
        "unitAggregationType": "sum",
        "eventKey": "event-key-123abc",
        "_links": {
          "self": {
            "href": "/api/v2/metrics/my-project/my-metric",
            "type": "application/json"
          }
        }
      },
      "primaryFunnel": {
        "key": "metric-group-key-123abc",
        "name": "My metric group",
        "kind": "funnel",
        "_links": {
          "parent": {
            "href": "/api/v2/projects/my-project",
            "type": "application/json"
          },
          "self": {
            "href": "/api/v2/projects/my-project/metric-groups/my-metric-group",
            "type": "application/json"
          }
        },
        "metrics": [
          {
            "key": "metric-key-123abc",
            "_versionId": "version-id-123abc",
            "name": "Example metric",
            "kind": "custom",
            "isNumeric": true,
            "unitAggregationType": "sum",
            "eventKey": "event-key-123abc",
            "_links": {
              "self": {
                "href": "/api/v2/metrics/my-project/my-metric",
                "type": "application/json"
              }
            },
            "nameInGroup": "Step 1",
            "randomizationUnits": [
              "user"
            ]
          }
        ]
      },
      "randomizationUnit": "user",
      "treatments": [
        {
          "_id": "122c9f3e-da26-4321-ba68-e0fc02eced58",
          "name": "Treatment 1",
          "allocationPercent": "10",
          "baseline": true
        }
      ],
      "secondaryMetrics": [
        {
          "key": "metric-key-123abc",
          "_versionId": "version-id-123abc",
          "name": "Example metric",
          "kind": "custom",
          "isNumeric": true,
          "unitAggregationType": "sum",
          "eventKey": "event-key-123abc",
          "_links": {
            "self": {
              "href": "/api/v2/metrics/my-project/my-metric",
              "type": "application/json"
            }
          }
        }
      ],
      "metrics": [
        {
          "key": "metric-key-123abc",
          "name": "My metric",
          "kind": "custom",
          "isNumeric": true,
          "eventKey": "event-key-123abc",
          "_links": {
            "self": {
              "href": "/api/v2/metrics/my-project/my-metric",
              "type": "application/json"
            }
          },
          "metrics": [
            {
              "key": "metric-key-123abc",
              "_versionId": "version-id-123abc",
              "name": "Example metric",
              "kind": "custom",
              "isNumeric": true,
              "unitAggregationType": "sum",
              "eventKey": "event-key-123abc",
              "_links": {
                "self": {
                  "href": "/api/v2/metrics/my-project/my-metric",
                  "type": "application/json"
                }
              },
              "nameInGroup": "Step 1",
              "randomizationUnits": [
                "user"
              ]
            }
          ]
        }
      ],
      "layerSnapshot": {
        "key": "checkout-flow",
        "name": "Checkout Flow",
        "reservationPercent": 10,
        "otherReservationPercent": 70
      }
    },
    "draftIteration": {
      "_id": "12ab3c45de678910fgh12345",
      "hypothesis": "The new button placement will increase conversion",
      "status": "running",
      "winningTreatmentId": "122c9f3e-da26-4321-ba68-e0fc02eced58",
      "winningReason": "We ran this iteration for two weeks and the winning variation was clear",
      "canReshuffleTraffic": true,
      "reallocationFrequencyMillis": 3600000,
      "primaryMetric": {
        "key": "metric-key-123abc",
        "name": "My metric",
        "kind": "custom",
        "isNumeric": true,
        "eventKey": "event-key-123abc",
        "_links": {
          "self": {
            "href": "/api/v2/metrics/my-project/my-metric",
            "type": "application/json"
          }
        },
        "metrics": [
          {
            "key": "metric-key-123abc",
            "_versionId": "version-id-123abc",
            "name": "Example metric",
            "kind": "custom",
            "isNumeric": true,
            "unitAggregationType": "sum",
            "eventKey": "event-key-123abc",
            "_links": {
              "self": {
                "href": "/api/v2/metrics/my-project/my-metric",
                "type": "application/json"
              }
            },
            "nameInGroup": "Step 1",
            "randomizationUnits": [
              "user"
            ]
          }
        ]
      },
      "primarySingleMetric": {
        "key": "metric-key-123abc",
        "_versionId": "version-id-123abc",
        "name": "Example metric",
        "kind": "custom",
        "isNumeric": true,
        "unitAggregationType": "sum",
        "eventKey": "event-key-123abc",
        "_links": {
          "self": {
            "href": "/api/v2/metrics/my-project/my-metric",
            "type": "application/json"
          }
        }
      },
      "primaryFunnel": {
        "key": "metric-group-key-123abc",
        "name": "My metric group",
        "kind": "funnel",
        "_links": {
          "parent": {
            "href": "/api/v2/projects/my-project",
            "type": "application/json"
          },
          "self": {
            "href": "/api/v2/projects/my-project/metric-groups/my-metric-group",
            "type": "application/json"
          }
        },
        "metrics": [
          {
            "key": "metric-key-123abc",
            "_versionId": "version-id-123abc",
            "name": "Example metric",
            "kind": "custom",
            "isNumeric": true,
            "unitAggregationType": "sum",
            "eventKey": "event-key-123abc",
            "_links": {
              "self": {
                "href": "/api/v2/metrics/my-project/my-metric",
                "type": "application/json"
              }
            },
            "nameInGroup": "Step 1",
            "randomizationUnits": [
              "user"
            ]
          }
        ]
      },
      "randomizationUnit": "user",
      "treatments": [
        {
          "_id": "122c9f3e-da26-4321-ba68-e0fc02eced58",
          "name": "Treatment 1",
          "allocationPercent": "10",
          "baseline": true
        }
      ],
      "secondaryMetrics": [
        {
          "key": "metric-key-123abc",
          "_versionId": "version-id-123abc",
          "name": "Example metric",
          "kind": "custom",
          "isNumeric": true,
          "unitAggregationType": "sum",
          "eventKey": "event-key-123abc",
          "_links": {
            "self": {
              "href": "/api/v2/metrics/my-project/my-metric",
              "type": "application/json"
            }
          }
        }
      ],
      "metrics": [
        {
          "key": "metric-key-123abc",
          "name": "My metric",
          "kind": "custom",
          "isNumeric": true,
          "eventKey": "event-key-123abc",
          "_links": {
            "self": {
              "href": "/api/v2/metrics/my-project/my-metric",
              "type": "application/json"
            }
          },
          "metrics": [
            {
              "key": "metric-key-123abc",
              "_versionId": "version-id-123abc",
              "name": "Example metric",
              "kind": "custom",
              "isNumeric": true,
              "unitAggregationType": "sum",
              "eventKey": "event-key-123abc",
              "_links": {
                "self": {
                  "href": "/api/v2/metrics/my-project/my-metric",
                  "type": "application/json"
                }
              },
              "nameInGroup": "Step 1",
              "randomizationUnits": [
                "user"
              ]
            }
          ]
        }
      ],
      "layerSnapshot": {
        "key": "checkout-flow",
        "name": "Checkout Flow",
        "reservationPercent": 10,
        "otherReservationPercent": 70
      }
    },
    "previousIterations": [
      {
        "_id": "12ab3c45de678910fgh12345",
        "hypothesis": "The new button placement will increase conversion",
        "status": "running",
        "winningTreatmentId": "122c9f3e-da26-4321-ba68-e0fc02eced58",
        "winningReason": "We ran this iteration for two weeks and the winning variation was clear",
        "canReshuffleTraffic": true,
        "reallocationFrequencyMillis": 3600000,
        "primaryMetric": {
          "key": "metric-key-123abc",
          "name": "My metric",
          "kind": "custom",
          "isNumeric": true,
          "eventKey": "event-key-123abc",
          "_links": {
            "self": {
              "href": "/api/v2/metrics/my-project/my-metric",
              "type": "application/json"
            }
          },
          "metrics": [
            {
              "key": "metric-key-123abc",
              "_versionId": "version-id-123abc",
              "name": "Example metric",
              "kind": "custom",
              "isNumeric": true,
              "unitAggregationType": "sum",
              "eventKey": "event-key-123abc",
              "_links": {
                "self": {
                  "href": "/api/v2/metrics/my-project/my-metric",
                  "type": "application/json"
                }
              },
              "nameInGroup": "Step 1",
              "randomizationUnits": [
                "user"
              ]
            }
          ]
        },
        "primarySingleMetric": {
          "key": "metric-key-123abc",
          "_versionId": "version-id-123abc",
          "name": "Example metric",
          "kind": "custom",
          "isNumeric": true,
          "unitAggregationType": "sum",
          "eventKey": "event-key-123abc",
          "_links": {
            "self": {
              "href": "/api/v2/metrics/my-project/my-metric",
              "type": "application/json"
            }
          }
        },
        "primaryFunnel": {
          "key": "metric-group-key-123abc",
          "name": "My metric group",
          "kind": "funnel",
          "_links": {
            "parent": {
              "href": "/api/v2/projects/my-project",
              "type": "application/json"
            },
            "self": {
              "href": "/api/v2/projects/my-project/metric-groups/my-metric-group",
              "type": "application/json"
            }
          },
          "metrics": [
            {
              "key": "metric-key-123abc",
              "_versionId": "version-id-123abc",
              "name": "Example metric",
              "kind": "custom",
              "isNumeric": true,
              "unitAggregationType": "sum",
              "eventKey": "event-key-123abc",
              "_links": {
                "self": {
                  "href": "/api/v2/metrics/my-project/my-metric",
                  "type": "application/json"
                }
              },
              "nameInGroup": "Step 1",
              "randomizationUnits": [
                "user"
              ]
            }
          ]
        },
        "randomizationUnit": "user",
        "treatments": [
          {
            "_id": "122c9f3e-da26-4321-ba68-e0fc02eced58",
            "name": "Treatment 1",
            "allocationPercent": "10",
            "baseline": true
          }
        ],
        "secondaryMetrics": [
          {
            "key": "metric-key-123abc",
            "_versionId": "version-id-123abc",
            "name": "Example metric",
            "kind": "custom",
            "isNumeric": true,
            "unitAggregationType": "sum",
            "eventKey": "event-key-123abc",
            "_links": {
              "self": {
                "href": "/api/v2/metrics/my-project/my-metric",
                "type": "application/json"
              }
            }
          }
        ],
        "metrics": [
          {
            "key": "metric-key-123abc",
            "name": "My metric",
            "kind": "custom",
            "isNumeric": true,
            "eventKey": "event-key-123abc",
            "_links": {
              "self": {
                "href": "/api/v2/metrics/my-project/my-metric",
                "type": "application/json"
              }
            },
            "metrics": [
              {
                "key": "metric-key-123abc",
                "_versionId": "version-id-123abc",
                "name": "Example metric",
                "kind": "custom",
                "isNumeric": true,
                "unitAggregationType": "sum",
                "eventKey": "event-key-123abc",
                "_links": {
                  "self": {
                    "href": "/api/v2/metrics/my-project/my-metric",
                    "type": "application/json"
                  }
                },
                "nameInGroup": "Step 1",
                "randomizationUnits": [
                  "user"
                ]
              }
            ]
          }
        ],
        "layerSnapshot": {
          "key": "checkout-flow",
          "name": "Checkout Flow",
          "reservationPercent": 10,
          "otherReservationPercent": 70
        }
      }
    ]
  }
}