v5

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

Holdouts (beta)

Patch holdout

Updates an existing holdout, and returns the updated holdout. Updating holdouts uses the semantic patch format.

To make a semantic patch request, you must append domain-model=launchdarkly.semanticpatch to your Content-Type header. To learn more, read Updates using semantic patch.

Instructions

Semantic patch requests support the following kind instructions for updating holdouts.

<details> <summary>Click to expand instructions for <strong>updating holdouts</strong></summary>

endHoldout

Ends a holdout.

Parameters

None.

Here's an example:

{
  "comment": "Optional comment describing why the holdout is ending",
  "instructions": [{
    "kind": "endHoldout"
  }]
}

removeExperiment

Removes an experiment from a holdout.

Parameters

value: The key of the experiment to remove

Here's an example:

{
  "comment": "Optional comment describing the change",
  "instructions": [{
    "kind": "removeExperiment",
    "value": "experiment-key"
  }]
}

updateDescription

Updates the description of the holdout.

Parameters

value: The new description.

Here's an example:

{
  "comment": "Optional comment describing the update",
  "instructions": [{
    "kind": "updateDescription",
    "value": "Updated holdout description"
  }]
}

updateName

Updates the name of the holdout.

Parameters

value: The new name.

Here's an example:

{
  "comment": "Optional comment describing the update",
  "instructions": [{
    "kind": "updateName",
    "value": "Updated holdout name"
  }]
}

</details>

patch/api/v2/projects/{projectKey}/environments/{environmentKey}/holdouts/{holdoutKey}

Path parameters

projectKeystring string required

The project key

environmentKeystring string required

The environment key

holdoutKeystring string required

The holdout key

Request body

commentstring

Optional comment describing the update

instructionsInstruction[] required

Example request

{
  "comment": "Optional comment"
}

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
        }
      }
    ]
  }
}