Patch holdout

curl --request PATCH \
  --url https://app.launchdarkly.com/api/v2/projects/{projectKey}/environments/{environmentKey}/holdouts/{holdoutKey} \
  --header 'Authorization: <api-key>' \
  --header 'Content-Type: application/json' \
  --data '
{
  "comment": "Optional comment describing the update",
  "instructions": [
    {
      "kind": "updateName",
      "value": "Updated holdout name"
    }
  ]
}
'

import requests

url = "https://app.launchdarkly.com/api/v2/projects/{projectKey}/environments/{environmentKey}/holdouts/{holdoutKey}"

payload = {
    "comment": "Optional comment describing the update",
    "instructions": [
        {
            "kind": "updateName",
            "value": "Updated holdout name"
        }
    ]
}
headers = {
    "Authorization": "<api-key>",
    "Content-Type": "application/json"
}

response = requests.patch(url, json=payload, headers=headers)

print(response.text)

const options = {
  method: 'PATCH',
  headers: {Authorization: '<api-key>', 'Content-Type': 'application/json'},
  body: JSON.stringify({
    comment: 'Optional comment describing the update',
    instructions: [{kind: 'updateName', value: 'Updated holdout name'}]
  })
};

fetch('https://app.launchdarkly.com/api/v2/projects/{projectKey}/environments/{environmentKey}/holdouts/{holdoutKey}', options)
  .then(res => res.json())
  .then(res => console.log(res))
  .catch(err => console.error(err));

<?php

$curl = curl_init();

curl_setopt_array($curl, [
  CURLOPT_URL => "https://app.launchdarkly.com/api/v2/projects/{projectKey}/environments/{environmentKey}/holdouts/{holdoutKey}",
  CURLOPT_RETURNTRANSFER => true,
  CURLOPT_ENCODING => "",
  CURLOPT_MAXREDIRS => 10,
  CURLOPT_TIMEOUT => 30,
  CURLOPT_HTTP_VERSION => CURL_HTTP_VERSION_1_1,
  CURLOPT_CUSTOMREQUEST => "PATCH",
  CURLOPT_POSTFIELDS => json_encode([
    'comment' => 'Optional comment describing the update',
    'instructions' => [
        [
                'kind' => 'updateName',
                'value' => 'Updated holdout name'
        ]
    ]
  ]),
  CURLOPT_HTTPHEADER => [
    "Authorization: <api-key>",
    "Content-Type: application/json"
  ],
]);

$response = curl_exec($curl);
$err = curl_error($curl);

curl_close($curl);

if ($err) {
  echo "cURL Error #:" . $err;
} else {
  echo $response;
}

package main

import (
	"fmt"
	"strings"
	"net/http"
	"io"
)

func main() {

	url := "https://app.launchdarkly.com/api/v2/projects/{projectKey}/environments/{environmentKey}/holdouts/{holdoutKey}"

	payload := strings.NewReader("{\n  \"comment\": \"Optional comment describing the update\",\n  \"instructions\": [\n    {\n      \"kind\": \"updateName\",\n      \"value\": \"Updated holdout name\"\n    }\n  ]\n}")

	req, _ := http.NewRequest("PATCH", url, payload)

	req.Header.Add("Authorization", "<api-key>")
	req.Header.Add("Content-Type", "application/json")

	res, _ := http.DefaultClient.Do(req)

	defer res.Body.Close()
	body, _ := io.ReadAll(res.Body)

	fmt.Println(string(body))

}

HttpResponse<String> response = Unirest.patch("https://app.launchdarkly.com/api/v2/projects/{projectKey}/environments/{environmentKey}/holdouts/{holdoutKey}")
  .header("Authorization", "<api-key>")
  .header("Content-Type", "application/json")
  .body("{\n  \"comment\": \"Optional comment describing the update\",\n  \"instructions\": [\n    {\n      \"kind\": \"updateName\",\n      \"value\": \"Updated holdout name\"\n    }\n  ]\n}")
  .asString();

require 'uri'
require 'net/http'

url = URI("https://app.launchdarkly.com/api/v2/projects/{projectKey}/environments/{environmentKey}/holdouts/{holdoutKey}")

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

request = Net::HTTP::Patch.new(url)
request["Authorization"] = '<api-key>'
request["Content-Type"] = 'application/json'
request.body = "{\n  \"comment\": \"Optional comment describing the update\",\n  \"instructions\": [\n    {\n      \"kind\": \"updateName\",\n      \"value\": \"Updated holdout name\"\n    }\n  ]\n}"

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

{
  "_id": "<string>",
  "status": "created",
  "holdoutAmount": "<string>",
  "createdAt": 123,
  "updatedAt": 123,
  "baseExperiment": {
    "key": "experiment-key-123abc",
    "name": "Example experiment",
    "_maintainerId": "12ab3c45de678910fgh12345",
    "_creationDate": "1654104600000",
    "environmentKey": "<string>",
    "_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"
      }
    },
    "_id": "12ab3c45de678910fgh12345",
    "description": "An example experiment, used in testing",
    "methodology": "bayesian",
    "dataSource": "snowflake",
    "archivedDate": "1654104600000",
    "tags": [
      "experiment",
      "feature"
    ],
    "holdoutId": "f3b74309-d581-44e1-8a2b-bb2933b4fe40",
    "currentIteration": {
      "hypothesis": "The new button placement will increase conversion",
      "status": "running",
      "createdAt": "1654104600000",
      "_id": "12ab3c45de678910fgh12345",
      "startedAt": "1655314200000",
      "endedAt": "1656610200000",
      "winningTreatmentId": "122c9f3e-da26-4321-ba68-e0fc02eced58",
      "winningReason": "We ran this iteration for two weeks and the winning variation was clear",
      "canReshuffleTraffic": true,
      "flags": {},
      "reallocationFrequencyMillis": 3600000,
      "version": 0,
      "primaryMetric": {
        "key": "metric-key-123abc",
        "_versionId": "<string>",
        "name": "My metric",
        "kind": "custom",
        "_links": {
          "self": {
            "href": "/api/v2/metrics/my-project/my-metric",
            "type": "application/json"
          }
        },
        "isGroup": true,
        "isNumeric": true,
        "eventKey": "event-key-123abc",
        "metrics": [
          {
            "key": "metric-key-123abc",
            "name": "Example metric",
            "kind": "custom",
            "_links": {
              "self": {
                "href": "/api/v2/metrics/my-project/my-metric",
                "type": "application/json"
              }
            },
            "_versionId": "version-id-123abc",
            "isNumeric": true,
            "unitAggregationType": "sum",
            "analysisType": "mean",
            "eventKey": "event-key-123abc",
            "analysisUnit": "<string>",
            "nameInGroup": "Step 1",
            "randomizationUnits": [
              "user"
            ],
            "analysisUnits": [
              "user"
            ]
          }
        ],
        "analysisType": "mean",
        "analysisUnit": "user"
      },
      "primarySingleMetric": {
        "key": "metric-key-123abc",
        "name": "Example metric",
        "kind": "custom",
        "_links": {
          "self": {
            "href": "/api/v2/metrics/my-project/my-metric",
            "type": "application/json"
          }
        },
        "_versionId": "version-id-123abc",
        "isNumeric": true,
        "unitAggregationType": "sum",
        "analysisType": "mean",
        "eventKey": "event-key-123abc",
        "analysisUnit": "<string>"
      },
      "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",
            "name": "Example metric",
            "kind": "custom",
            "_links": {
              "self": {
                "href": "/api/v2/metrics/my-project/my-metric",
                "type": "application/json"
              }
            },
            "_versionId": "version-id-123abc",
            "isNumeric": true,
            "unitAggregationType": "sum",
            "analysisType": "mean",
            "eventKey": "event-key-123abc",
            "analysisUnit": "<string>",
            "nameInGroup": "Step 1",
            "randomizationUnits": [
              "user"
            ],
            "analysisUnits": [
              "user"
            ]
          }
        ]
      },
      "randomizationUnit": "user",
      "attributes": [
        "<string>"
      ],
      "treatments": [
        {
          "name": "Treatment 1",
          "allocationPercent": "10",
          "_id": "122c9f3e-da26-4321-ba68-e0fc02eced58",
          "baseline": true,
          "parameters": [
            {
              "variationId": "<string>",
              "flagKey": "<string>"
            }
          ]
        }
      ],
      "secondaryMetrics": [
        {
          "key": "metric-key-123abc",
          "name": "Example metric",
          "kind": "custom",
          "_links": {
            "self": {
              "href": "/api/v2/metrics/my-project/my-metric",
              "type": "application/json"
            }
          },
          "_versionId": "version-id-123abc",
          "isNumeric": true,
          "unitAggregationType": "sum",
          "analysisType": "mean",
          "eventKey": "event-key-123abc",
          "analysisUnit": "<string>"
        }
      ],
      "metrics": [
        {
          "key": "metric-key-123abc",
          "_versionId": "<string>",
          "name": "My metric",
          "kind": "custom",
          "_links": {
            "self": {
              "href": "/api/v2/metrics/my-project/my-metric",
              "type": "application/json"
            }
          },
          "isGroup": true,
          "isNumeric": true,
          "eventKey": "event-key-123abc",
          "metrics": [
            {
              "key": "metric-key-123abc",
              "name": "Example metric",
              "kind": "custom",
              "_links": {
                "self": {
                  "href": "/api/v2/metrics/my-project/my-metric",
                  "type": "application/json"
                }
              },
              "_versionId": "version-id-123abc",
              "isNumeric": true,
              "unitAggregationType": "sum",
              "analysisType": "mean",
              "eventKey": "event-key-123abc",
              "analysisUnit": "<string>",
              "nameInGroup": "Step 1",
              "randomizationUnits": [
                "user"
              ],
              "analysisUnits": [
                "user"
              ]
            }
          ],
          "analysisType": "mean",
          "analysisUnit": "user"
        }
      ],
      "layerSnapshot": {
        "key": "checkout-flow",
        "name": "Checkout Flow",
        "reservationPercent": 10,
        "otherReservationPercent": 70
      },
      "covariateInfo": {
        "id": "74a49a2b-4834-4246-917e-5d85231d8c2a",
        "fileName": "covariate.csv",
        "createdAt": "1654104600000"
      }
    },
    "type": "experiment",
    "_access": {
      "denied": [
        {
          "action": "<string>",
          "reason": {
            "effect": "allow",
            "resources": [
              "proj/*:env/*;qa_*:/flag/*"
            ],
            "notResources": [
              "<string>"
            ],
            "actions": [
              "*"
            ],
            "notActions": [
              "<string>"
            ],
            "role_name": "<string>"
          }
        }
      ],
      "allowed": [
        {
          "action": "<string>",
          "reason": {
            "effect": "allow",
            "resources": [
              "proj/*:env/*;qa_*:/flag/*"
            ],
            "notResources": [
              "<string>"
            ],
            "actions": [
              "*"
            ],
            "notActions": [
              "<string>"
            ],
            "role_name": "<string>"
          }
        }
      ]
    },
    "draftIteration": {
      "hypothesis": "The new button placement will increase conversion",
      "status": "running",
      "createdAt": "1654104600000",
      "_id": "12ab3c45de678910fgh12345",
      "startedAt": "1655314200000",
      "endedAt": "1656610200000",
      "winningTreatmentId": "122c9f3e-da26-4321-ba68-e0fc02eced58",
      "winningReason": "We ran this iteration for two weeks and the winning variation was clear",
      "canReshuffleTraffic": true,
      "flags": {},
      "reallocationFrequencyMillis": 3600000,
      "version": 0,
      "primaryMetric": {
        "key": "metric-key-123abc",
        "_versionId": "<string>",
        "name": "My metric",
        "kind": "custom",
        "_links": {
          "self": {
            "href": "/api/v2/metrics/my-project/my-metric",
            "type": "application/json"
          }
        },
        "isGroup": true,
        "isNumeric": true,
        "eventKey": "event-key-123abc",
        "metrics": [
          {
            "key": "metric-key-123abc",
            "name": "Example metric",
            "kind": "custom",
            "_links": {
              "self": {
                "href": "/api/v2/metrics/my-project/my-metric",
                "type": "application/json"
              }
            },
            "_versionId": "version-id-123abc",
            "isNumeric": true,
            "unitAggregationType": "sum",
            "analysisType": "mean",
            "eventKey": "event-key-123abc",
            "analysisUnit": "<string>",
            "nameInGroup": "Step 1",
            "randomizationUnits": [
              "user"
            ],
            "analysisUnits": [
              "user"
            ]
          }
        ],
        "analysisType": "mean",
        "analysisUnit": "user"
      },
      "primarySingleMetric": {
        "key": "metric-key-123abc",
        "name": "Example metric",
        "kind": "custom",
        "_links": {
          "self": {
            "href": "/api/v2/metrics/my-project/my-metric",
            "type": "application/json"
          }
        },
        "_versionId": "version-id-123abc",
        "isNumeric": true,
        "unitAggregationType": "sum",
        "analysisType": "mean",
        "eventKey": "event-key-123abc",
        "analysisUnit": "<string>"
      },
      "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",
            "name": "Example metric",
            "kind": "custom",
            "_links": {
              "self": {
                "href": "/api/v2/metrics/my-project/my-metric",
                "type": "application/json"
              }
            },
            "_versionId": "version-id-123abc",
            "isNumeric": true,
            "unitAggregationType": "sum",
            "analysisType": "mean",
            "eventKey": "event-key-123abc",
            "analysisUnit": "<string>",
            "nameInGroup": "Step 1",
            "randomizationUnits": [
              "user"
            ],
            "analysisUnits": [
              "user"
            ]
          }
        ]
      },
      "randomizationUnit": "user",
      "attributes": [
        "<string>"
      ],
      "treatments": [
        {
          "name": "Treatment 1",
          "allocationPercent": "10",
          "_id": "122c9f3e-da26-4321-ba68-e0fc02eced58",
          "baseline": true,
          "parameters": [
            {
              "variationId": "<string>",
              "flagKey": "<string>"
            }
          ]
        }
      ],
      "secondaryMetrics": [
        {
          "key": "metric-key-123abc",
          "name": "Example metric",
          "kind": "custom",
          "_links": {
            "self": {
              "href": "/api/v2/metrics/my-project/my-metric",
              "type": "application/json"
            }
          },
          "_versionId": "version-id-123abc",
          "isNumeric": true,
          "unitAggregationType": "sum",
          "analysisType": "mean",
          "eventKey": "event-key-123abc",
          "analysisUnit": "<string>"
        }
      ],
      "metrics": [
        {
          "key": "metric-key-123abc",
          "_versionId": "<string>",
          "name": "My metric",
          "kind": "custom",
          "_links": {
            "self": {
              "href": "/api/v2/metrics/my-project/my-metric",
              "type": "application/json"
            }
          },
          "isGroup": true,
          "isNumeric": true,
          "eventKey": "event-key-123abc",
          "metrics": [
            {
              "key": "metric-key-123abc",
              "name": "Example metric",
              "kind": "custom",
              "_links": {
                "self": {
                  "href": "/api/v2/metrics/my-project/my-metric",
                  "type": "application/json"
                }
              },
              "_versionId": "version-id-123abc",
              "isNumeric": true,
              "unitAggregationType": "sum",
              "analysisType": "mean",
              "eventKey": "event-key-123abc",
              "analysisUnit": "<string>",
              "nameInGroup": "Step 1",
              "randomizationUnits": [
                "user"
              ],
              "analysisUnits": [
                "user"
              ]
            }
          ],
          "analysisType": "mean",
          "analysisUnit": "user"
        }
      ],
      "layerSnapshot": {
        "key": "checkout-flow",
        "name": "Checkout Flow",
        "reservationPercent": 10,
        "otherReservationPercent": 70
      },
      "covariateInfo": {
        "id": "74a49a2b-4834-4246-917e-5d85231d8c2a",
        "fileName": "covariate.csv",
        "createdAt": "1654104600000"
      }
    },
    "previousIterations": [
      {
        "hypothesis": "The new button placement will increase conversion",
        "status": "running",
        "createdAt": "1654104600000",
        "_id": "12ab3c45de678910fgh12345",
        "startedAt": "1655314200000",
        "endedAt": "1656610200000",
        "winningTreatmentId": "122c9f3e-da26-4321-ba68-e0fc02eced58",
        "winningReason": "We ran this iteration for two weeks and the winning variation was clear",
        "canReshuffleTraffic": true,
        "flags": {},
        "reallocationFrequencyMillis": 3600000,
        "version": 0,
        "primaryMetric": {
          "key": "metric-key-123abc",
          "_versionId": "<string>",
          "name": "My metric",
          "kind": "custom",
          "_links": {
            "self": {
              "href": "/api/v2/metrics/my-project/my-metric",
              "type": "application/json"
            }
          },
          "isGroup": true,
          "isNumeric": true,
          "eventKey": "event-key-123abc",
          "metrics": [
            {
              "key": "metric-key-123abc",
              "name": "Example metric",
              "kind": "custom",
              "_links": {
                "self": {
                  "href": "/api/v2/metrics/my-project/my-metric",
                  "type": "application/json"
                }
              },
              "_versionId": "version-id-123abc",
              "isNumeric": true,
              "unitAggregationType": "sum",
              "analysisType": "mean",
              "eventKey": "event-key-123abc",
              "analysisUnit": "<string>",
              "nameInGroup": "Step 1",
              "randomizationUnits": [
                "user"
              ],
              "analysisUnits": [
                "user"
              ]
            }
          ],
          "analysisType": "mean",
          "analysisUnit": "user"
        },
        "primarySingleMetric": {
          "key": "metric-key-123abc",
          "name": "Example metric",
          "kind": "custom",
          "_links": {
            "self": {
              "href": "/api/v2/metrics/my-project/my-metric",
              "type": "application/json"
            }
          },
          "_versionId": "version-id-123abc",
          "isNumeric": true,
          "unitAggregationType": "sum",
          "analysisType": "mean",
          "eventKey": "event-key-123abc",
          "analysisUnit": "<string>"
        },
        "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",
              "name": "Example metric",
              "kind": "custom",
              "_links": {
                "self": {
                  "href": "/api/v2/metrics/my-project/my-metric",
                  "type": "application/json"
                }
              },
              "_versionId": "version-id-123abc",
              "isNumeric": true,
              "unitAggregationType": "sum",
              "analysisType": "mean",
              "eventKey": "event-key-123abc",
              "analysisUnit": "<string>",
              "nameInGroup": "Step 1",
              "randomizationUnits": [
                "user"
              ],
              "analysisUnits": [
                "user"
              ]
            }
          ]
        },
        "randomizationUnit": "user",
        "attributes": [
          "<string>"
        ],
        "treatments": [
          {
            "name": "Treatment 1",
            "allocationPercent": "10",
            "_id": "122c9f3e-da26-4321-ba68-e0fc02eced58",
            "baseline": true,
            "parameters": [
              {
                "variationId": "<string>",
                "flagKey": "<string>"
              }
            ]
          }
        ],
        "secondaryMetrics": [
          {
            "key": "metric-key-123abc",
            "name": "Example metric",
            "kind": "custom",
            "_links": {
              "self": {
                "href": "/api/v2/metrics/my-project/my-metric",
                "type": "application/json"
              }
            },
            "_versionId": "version-id-123abc",
            "isNumeric": true,
            "unitAggregationType": "sum",
            "analysisType": "mean",
            "eventKey": "event-key-123abc",
            "analysisUnit": "<string>"
          }
        ],
        "metrics": [
          {
            "key": "metric-key-123abc",
            "_versionId": "<string>",
            "name": "My metric",
            "kind": "custom",
            "_links": {
              "self": {
                "href": "/api/v2/metrics/my-project/my-metric",
                "type": "application/json"
              }
            },
            "isGroup": true,
            "isNumeric": true,
            "eventKey": "event-key-123abc",
            "metrics": [
              {
                "key": "metric-key-123abc",
                "name": "Example metric",
                "kind": "custom",
                "_links": {
                  "self": {
                    "href": "/api/v2/metrics/my-project/my-metric",
                    "type": "application/json"
                  }
                },
                "_versionId": "version-id-123abc",
                "isNumeric": true,
                "unitAggregationType": "sum",
                "analysisType": "mean",
                "eventKey": "event-key-123abc",
                "analysisUnit": "<string>",
                "nameInGroup": "Step 1",
                "randomizationUnits": [
                  "user"
                ],
                "analysisUnits": [
                  "user"
                ]
              }
            ],
            "analysisType": "mean",
            "analysisUnit": "user"
          }
        ],
        "layerSnapshot": {
          "key": "checkout-flow",
          "name": "Checkout Flow",
          "reservationPercent": 10,
          "otherReservationPercent": 70
        },
        "covariateInfo": {
          "id": "74a49a2b-4834-4246-917e-5d85231d8c2a",
          "fileName": "covariate.csv",
          "createdAt": "1654104600000"
        }
      }
    ],
    "analysisConfig": {
      "bayesianThreshold": "<string>",
      "significanceThreshold": "<string>",
      "testDirection": "<string>",
      "multipleComparisonCorrectionMethod": "bonferroni",
      "multipleComparisonCorrectionScope": "variations",
      "sequentialTestingEnabled": true
    },
    "mutableFieldsByStatus": {
      "not_started": {},
      "running": {},
      "stopped": {}
    }
  },
  "description": "<string>",
  "experiments": [
    {
      "key": "<string>",
      "name": "<string>",
      "environment": "<string>"
    }
  ]
}

{
  "code": "invalid_request",
  "message": "Invalid request body"
}

{
  "code": "unauthorized",
  "message": "Invalid access token"
}

{
  "code": "forbidden",
  "message": "Forbidden. Access to the requested resource was denied."
}

{
  "code": "not_found",
  "message": "Invalid resource identifier"
}

{
  "code": "rate_limited",
  "message": "You've exceeded the API rate limit. Try again later."
}

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.

Click to expand instructions for updating holdouts

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

PATCH

api

projects

{projectKey}

environments

{environmentKey}

holdouts

{holdoutKey}

Patch holdout

curl --request PATCH \
  --url https://app.launchdarkly.com/api/v2/projects/{projectKey}/environments/{environmentKey}/holdouts/{holdoutKey} \
  --header 'Authorization: <api-key>' \
  --header 'Content-Type: application/json' \
  --data '
{
  "comment": "Optional comment describing the update",
  "instructions": [
    {
      "kind": "updateName",
      "value": "Updated holdout name"
    }
  ]
}
'

import requests

url = "https://app.launchdarkly.com/api/v2/projects/{projectKey}/environments/{environmentKey}/holdouts/{holdoutKey}"

payload = {
    "comment": "Optional comment describing the update",
    "instructions": [
        {
            "kind": "updateName",
            "value": "Updated holdout name"
        }
    ]
}
headers = {
    "Authorization": "<api-key>",
    "Content-Type": "application/json"
}

response = requests.patch(url, json=payload, headers=headers)

print(response.text)

const options = {
  method: 'PATCH',
  headers: {Authorization: '<api-key>', 'Content-Type': 'application/json'},
  body: JSON.stringify({
    comment: 'Optional comment describing the update',
    instructions: [{kind: 'updateName', value: 'Updated holdout name'}]
  })
};

fetch('https://app.launchdarkly.com/api/v2/projects/{projectKey}/environments/{environmentKey}/holdouts/{holdoutKey}', options)
  .then(res => res.json())
  .then(res => console.log(res))
  .catch(err => console.error(err));

<?php

$curl = curl_init();

curl_setopt_array($curl, [
  CURLOPT_URL => "https://app.launchdarkly.com/api/v2/projects/{projectKey}/environments/{environmentKey}/holdouts/{holdoutKey}",
  CURLOPT_RETURNTRANSFER => true,
  CURLOPT_ENCODING => "",
  CURLOPT_MAXREDIRS => 10,
  CURLOPT_TIMEOUT => 30,
  CURLOPT_HTTP_VERSION => CURL_HTTP_VERSION_1_1,
  CURLOPT_CUSTOMREQUEST => "PATCH",
  CURLOPT_POSTFIELDS => json_encode([
    'comment' => 'Optional comment describing the update',
    'instructions' => [
        [
                'kind' => 'updateName',
                'value' => 'Updated holdout name'
        ]
    ]
  ]),
  CURLOPT_HTTPHEADER => [
    "Authorization: <api-key>",
    "Content-Type: application/json"
  ],
]);

$response = curl_exec($curl);
$err = curl_error($curl);

curl_close($curl);

if ($err) {
  echo "cURL Error #:" . $err;
} else {
  echo $response;
}

package main

import (
	"fmt"
	"strings"
	"net/http"
	"io"
)

func main() {

	url := "https://app.launchdarkly.com/api/v2/projects/{projectKey}/environments/{environmentKey}/holdouts/{holdoutKey}"

	payload := strings.NewReader("{\n  \"comment\": \"Optional comment describing the update\",\n  \"instructions\": [\n    {\n      \"kind\": \"updateName\",\n      \"value\": \"Updated holdout name\"\n    }\n  ]\n}")

	req, _ := http.NewRequest("PATCH", url, payload)

	req.Header.Add("Authorization", "<api-key>")
	req.Header.Add("Content-Type", "application/json")

	res, _ := http.DefaultClient.Do(req)

	defer res.Body.Close()
	body, _ := io.ReadAll(res.Body)

	fmt.Println(string(body))

}

HttpResponse<String> response = Unirest.patch("https://app.launchdarkly.com/api/v2/projects/{projectKey}/environments/{environmentKey}/holdouts/{holdoutKey}")
  .header("Authorization", "<api-key>")
  .header("Content-Type", "application/json")
  .body("{\n  \"comment\": \"Optional comment describing the update\",\n  \"instructions\": [\n    {\n      \"kind\": \"updateName\",\n      \"value\": \"Updated holdout name\"\n    }\n  ]\n}")
  .asString();

require 'uri'
require 'net/http'

url = URI("https://app.launchdarkly.com/api/v2/projects/{projectKey}/environments/{environmentKey}/holdouts/{holdoutKey}")

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

request = Net::HTTP::Patch.new(url)
request["Authorization"] = '<api-key>'
request["Content-Type"] = 'application/json'
request.body = "{\n  \"comment\": \"Optional comment describing the update\",\n  \"instructions\": [\n    {\n      \"kind\": \"updateName\",\n      \"value\": \"Updated holdout name\"\n    }\n  ]\n}"

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

{
  "_id": "<string>",
  "status": "created",
  "holdoutAmount": "<string>",
  "createdAt": 123,
  "updatedAt": 123,
  "baseExperiment": {
    "key": "experiment-key-123abc",
    "name": "Example experiment",
    "_maintainerId": "12ab3c45de678910fgh12345",
    "_creationDate": "1654104600000",
    "environmentKey": "<string>",
    "_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"
      }
    },
    "_id": "12ab3c45de678910fgh12345",
    "description": "An example experiment, used in testing",
    "methodology": "bayesian",
    "dataSource": "snowflake",
    "archivedDate": "1654104600000",
    "tags": [
      "experiment",
      "feature"
    ],
    "holdoutId": "f3b74309-d581-44e1-8a2b-bb2933b4fe40",
    "currentIteration": {
      "hypothesis": "The new button placement will increase conversion",
      "status": "running",
      "createdAt": "1654104600000",
      "_id": "12ab3c45de678910fgh12345",
      "startedAt": "1655314200000",
      "endedAt": "1656610200000",
      "winningTreatmentId": "122c9f3e-da26-4321-ba68-e0fc02eced58",
      "winningReason": "We ran this iteration for two weeks and the winning variation was clear",
      "canReshuffleTraffic": true,
      "flags": {},
      "reallocationFrequencyMillis": 3600000,
      "version": 0,
      "primaryMetric": {
        "key": "metric-key-123abc",
        "_versionId": "<string>",
        "name": "My metric",
        "kind": "custom",
        "_links": {
          "self": {
            "href": "/api/v2/metrics/my-project/my-metric",
            "type": "application/json"
          }
        },
        "isGroup": true,
        "isNumeric": true,
        "eventKey": "event-key-123abc",
        "metrics": [
          {
            "key": "metric-key-123abc",
            "name": "Example metric",
            "kind": "custom",
            "_links": {
              "self": {
                "href": "/api/v2/metrics/my-project/my-metric",
                "type": "application/json"
              }
            },
            "_versionId": "version-id-123abc",
            "isNumeric": true,
            "unitAggregationType": "sum",
            "analysisType": "mean",
            "eventKey": "event-key-123abc",
            "analysisUnit": "<string>",
            "nameInGroup": "Step 1",
            "randomizationUnits": [
              "user"
            ],
            "analysisUnits": [
              "user"
            ]
          }
        ],
        "analysisType": "mean",
        "analysisUnit": "user"
      },
      "primarySingleMetric": {
        "key": "metric-key-123abc",
        "name": "Example metric",
        "kind": "custom",
        "_links": {
          "self": {
            "href": "/api/v2/metrics/my-project/my-metric",
            "type": "application/json"
          }
        },
        "_versionId": "version-id-123abc",
        "isNumeric": true,
        "unitAggregationType": "sum",
        "analysisType": "mean",
        "eventKey": "event-key-123abc",
        "analysisUnit": "<string>"
      },
      "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",
            "name": "Example metric",
            "kind": "custom",
            "_links": {
              "self": {
                "href": "/api/v2/metrics/my-project/my-metric",
                "type": "application/json"
              }
            },
            "_versionId": "version-id-123abc",
            "isNumeric": true,
            "unitAggregationType": "sum",
            "analysisType": "mean",
            "eventKey": "event-key-123abc",
            "analysisUnit": "<string>",
            "nameInGroup": "Step 1",
            "randomizationUnits": [
              "user"
            ],
            "analysisUnits": [
              "user"
            ]
          }
        ]
      },
      "randomizationUnit": "user",
      "attributes": [
        "<string>"
      ],
      "treatments": [
        {
          "name": "Treatment 1",
          "allocationPercent": "10",
          "_id": "122c9f3e-da26-4321-ba68-e0fc02eced58",
          "baseline": true,
          "parameters": [
            {
              "variationId": "<string>",
              "flagKey": "<string>"
            }
          ]
        }
      ],
      "secondaryMetrics": [
        {
          "key": "metric-key-123abc",
          "name": "Example metric",
          "kind": "custom",
          "_links": {
            "self": {
              "href": "/api/v2/metrics/my-project/my-metric",
              "type": "application/json"
            }
          },
          "_versionId": "version-id-123abc",
          "isNumeric": true,
          "unitAggregationType": "sum",
          "analysisType": "mean",
          "eventKey": "event-key-123abc",
          "analysisUnit": "<string>"
        }
      ],
      "metrics": [
        {
          "key": "metric-key-123abc",
          "_versionId": "<string>",
          "name": "My metric",
          "kind": "custom",
          "_links": {
            "self": {
              "href": "/api/v2/metrics/my-project/my-metric",
              "type": "application/json"
            }
          },
          "isGroup": true,
          "isNumeric": true,
          "eventKey": "event-key-123abc",
          "metrics": [
            {
              "key": "metric-key-123abc",
              "name": "Example metric",
              "kind": "custom",
              "_links": {
                "self": {
                  "href": "/api/v2/metrics/my-project/my-metric",
                  "type": "application/json"
                }
              },
              "_versionId": "version-id-123abc",
              "isNumeric": true,
              "unitAggregationType": "sum",
              "analysisType": "mean",
              "eventKey": "event-key-123abc",
              "analysisUnit": "<string>",
              "nameInGroup": "Step 1",
              "randomizationUnits": [
                "user"
              ],
              "analysisUnits": [
                "user"
              ]
            }
          ],
          "analysisType": "mean",
          "analysisUnit": "user"
        }
      ],
      "layerSnapshot": {
        "key": "checkout-flow",
        "name": "Checkout Flow",
        "reservationPercent": 10,
        "otherReservationPercent": 70
      },
      "covariateInfo": {
        "id": "74a49a2b-4834-4246-917e-5d85231d8c2a",
        "fileName": "covariate.csv",
        "createdAt": "1654104600000"
      }
    },
    "type": "experiment",
    "_access": {
      "denied": [
        {
          "action": "<string>",
          "reason": {
            "effect": "allow",
            "resources": [
              "proj/*:env/*;qa_*:/flag/*"
            ],
            "notResources": [
              "<string>"
            ],
            "actions": [
              "*"
            ],
            "notActions": [
              "<string>"
            ],
            "role_name": "<string>"
          }
        }
      ],
      "allowed": [
        {
          "action": "<string>",
          "reason": {
            "effect": "allow",
            "resources": [
              "proj/*:env/*;qa_*:/flag/*"
            ],
            "notResources": [
              "<string>"
            ],
            "actions": [
              "*"
            ],
            "notActions": [
              "<string>"
            ],
            "role_name": "<string>"
          }
        }
      ]
    },
    "draftIteration": {
      "hypothesis": "The new button placement will increase conversion",
      "status": "running",
      "createdAt": "1654104600000",
      "_id": "12ab3c45de678910fgh12345",
      "startedAt": "1655314200000",
      "endedAt": "1656610200000",
      "winningTreatmentId": "122c9f3e-da26-4321-ba68-e0fc02eced58",
      "winningReason": "We ran this iteration for two weeks and the winning variation was clear",
      "canReshuffleTraffic": true,
      "flags": {},
      "reallocationFrequencyMillis": 3600000,
      "version": 0,
      "primaryMetric": {
        "key": "metric-key-123abc",
        "_versionId": "<string>",
        "name": "My metric",
        "kind": "custom",
        "_links": {
          "self": {
            "href": "/api/v2/metrics/my-project/my-metric",
            "type": "application/json"
          }
        },
        "isGroup": true,
        "isNumeric": true,
        "eventKey": "event-key-123abc",
        "metrics": [
          {
            "key": "metric-key-123abc",
            "name": "Example metric",
            "kind": "custom",
            "_links": {
              "self": {
                "href": "/api/v2/metrics/my-project/my-metric",
                "type": "application/json"
              }
            },
            "_versionId": "version-id-123abc",
            "isNumeric": true,
            "unitAggregationType": "sum",
            "analysisType": "mean",
            "eventKey": "event-key-123abc",
            "analysisUnit": "<string>",
            "nameInGroup": "Step 1",
            "randomizationUnits": [
              "user"
            ],
            "analysisUnits": [
              "user"
            ]
          }
        ],
        "analysisType": "mean",
        "analysisUnit": "user"
      },
      "primarySingleMetric": {
        "key": "metric-key-123abc",
        "name": "Example metric",
        "kind": "custom",
        "_links": {
          "self": {
            "href": "/api/v2/metrics/my-project/my-metric",
            "type": "application/json"
          }
        },
        "_versionId": "version-id-123abc",
        "isNumeric": true,
        "unitAggregationType": "sum",
        "analysisType": "mean",
        "eventKey": "event-key-123abc",
        "analysisUnit": "<string>"
      },
      "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",
            "name": "Example metric",
            "kind": "custom",
            "_links": {
              "self": {
                "href": "/api/v2/metrics/my-project/my-metric",
                "type": "application/json"
              }
            },
            "_versionId": "version-id-123abc",
            "isNumeric": true,
            "unitAggregationType": "sum",
            "analysisType": "mean",
            "eventKey": "event-key-123abc",
            "analysisUnit": "<string>",
            "nameInGroup": "Step 1",
            "randomizationUnits": [
              "user"
            ],
            "analysisUnits": [
              "user"
            ]
          }
        ]
      },
      "randomizationUnit": "user",
      "attributes": [
        "<string>"
      ],
      "treatments": [
        {
          "name": "Treatment 1",
          "allocationPercent": "10",
          "_id": "122c9f3e-da26-4321-ba68-e0fc02eced58",
          "baseline": true,
          "parameters": [
            {
              "variationId": "<string>",
              "flagKey": "<string>"
            }
          ]
        }
      ],
      "secondaryMetrics": [
        {
          "key": "metric-key-123abc",
          "name": "Example metric",
          "kind": "custom",
          "_links": {
            "self": {
              "href": "/api/v2/metrics/my-project/my-metric",
              "type": "application/json"
            }
          },
          "_versionId": "version-id-123abc",
          "isNumeric": true,
          "unitAggregationType": "sum",
          "analysisType": "mean",
          "eventKey": "event-key-123abc",
          "analysisUnit": "<string>"
        }
      ],
      "metrics": [
        {
          "key": "metric-key-123abc",
          "_versionId": "<string>",
          "name": "My metric",
          "kind": "custom",
          "_links": {
            "self": {
              "href": "/api/v2/metrics/my-project/my-metric",
              "type": "application/json"
            }
          },
          "isGroup": true,
          "isNumeric": true,
          "eventKey": "event-key-123abc",
          "metrics": [
            {
              "key": "metric-key-123abc",
              "name": "Example metric",
              "kind": "custom",
              "_links": {
                "self": {
                  "href": "/api/v2/metrics/my-project/my-metric",
                  "type": "application/json"
                }
              },
              "_versionId": "version-id-123abc",
              "isNumeric": true,
              "unitAggregationType": "sum",
              "analysisType": "mean",
              "eventKey": "event-key-123abc",
              "analysisUnit": "<string>",
              "nameInGroup": "Step 1",
              "randomizationUnits": [
                "user"
              ],
              "analysisUnits": [
                "user"
              ]
            }
          ],
          "analysisType": "mean",
          "analysisUnit": "user"
        }
      ],
      "layerSnapshot": {
        "key": "checkout-flow",
        "name": "Checkout Flow",
        "reservationPercent": 10,
        "otherReservationPercent": 70
      },
      "covariateInfo": {
        "id": "74a49a2b-4834-4246-917e-5d85231d8c2a",
        "fileName": "covariate.csv",
        "createdAt": "1654104600000"
      }
    },
    "previousIterations": [
      {
        "hypothesis": "The new button placement will increase conversion",
        "status": "running",
        "createdAt": "1654104600000",
        "_id": "12ab3c45de678910fgh12345",
        "startedAt": "1655314200000",
        "endedAt": "1656610200000",
        "winningTreatmentId": "122c9f3e-da26-4321-ba68-e0fc02eced58",
        "winningReason": "We ran this iteration for two weeks and the winning variation was clear",
        "canReshuffleTraffic": true,
        "flags": {},
        "reallocationFrequencyMillis": 3600000,
        "version": 0,
        "primaryMetric": {
          "key": "metric-key-123abc",
          "_versionId": "<string>",
          "name": "My metric",
          "kind": "custom",
          "_links": {
            "self": {
              "href": "/api/v2/metrics/my-project/my-metric",
              "type": "application/json"
            }
          },
          "isGroup": true,
          "isNumeric": true,
          "eventKey": "event-key-123abc",
          "metrics": [
            {
              "key": "metric-key-123abc",
              "name": "Example metric",
              "kind": "custom",
              "_links": {
                "self": {
                  "href": "/api/v2/metrics/my-project/my-metric",
                  "type": "application/json"
                }
              },
              "_versionId": "version-id-123abc",
              "isNumeric": true,
              "unitAggregationType": "sum",
              "analysisType": "mean",
              "eventKey": "event-key-123abc",
              "analysisUnit": "<string>",
              "nameInGroup": "Step 1",
              "randomizationUnits": [
                "user"
              ],
              "analysisUnits": [
                "user"
              ]
            }
          ],
          "analysisType": "mean",
          "analysisUnit": "user"
        },
        "primarySingleMetric": {
          "key": "metric-key-123abc",
          "name": "Example metric",
          "kind": "custom",
          "_links": {
            "self": {
              "href": "/api/v2/metrics/my-project/my-metric",
              "type": "application/json"
            }
          },
          "_versionId": "version-id-123abc",
          "isNumeric": true,
          "unitAggregationType": "sum",
          "analysisType": "mean",
          "eventKey": "event-key-123abc",
          "analysisUnit": "<string>"
        },
        "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",
              "name": "Example metric",
              "kind": "custom",
              "_links": {
                "self": {
                  "href": "/api/v2/metrics/my-project/my-metric",
                  "type": "application/json"
                }
              },
              "_versionId": "version-id-123abc",
              "isNumeric": true,
              "unitAggregationType": "sum",
              "analysisType": "mean",
              "eventKey": "event-key-123abc",
              "analysisUnit": "<string>",
              "nameInGroup": "Step 1",
              "randomizationUnits": [
                "user"
              ],
              "analysisUnits": [
                "user"
              ]
            }
          ]
        },
        "randomizationUnit": "user",
        "attributes": [
          "<string>"
        ],
        "treatments": [
          {
            "name": "Treatment 1",
            "allocationPercent": "10",
            "_id": "122c9f3e-da26-4321-ba68-e0fc02eced58",
            "baseline": true,
            "parameters": [
              {
                "variationId": "<string>",
                "flagKey": "<string>"
              }
            ]
          }
        ],
        "secondaryMetrics": [
          {
            "key": "metric-key-123abc",
            "name": "Example metric",
            "kind": "custom",
            "_links": {
              "self": {
                "href": "/api/v2/metrics/my-project/my-metric",
                "type": "application/json"
              }
            },
            "_versionId": "version-id-123abc",
            "isNumeric": true,
            "unitAggregationType": "sum",
            "analysisType": "mean",
            "eventKey": "event-key-123abc",
            "analysisUnit": "<string>"
          }
        ],
        "metrics": [
          {
            "key": "metric-key-123abc",
            "_versionId": "<string>",
            "name": "My metric",
            "kind": "custom",
            "_links": {
              "self": {
                "href": "/api/v2/metrics/my-project/my-metric",
                "type": "application/json"
              }
            },
            "isGroup": true,
            "isNumeric": true,
            "eventKey": "event-key-123abc",
            "metrics": [
              {
                "key": "metric-key-123abc",
                "name": "Example metric",
                "kind": "custom",
                "_links": {
                  "self": {
                    "href": "/api/v2/metrics/my-project/my-metric",
                    "type": "application/json"
                  }
                },
                "_versionId": "version-id-123abc",
                "isNumeric": true,
                "unitAggregationType": "sum",
                "analysisType": "mean",
                "eventKey": "event-key-123abc",
                "analysisUnit": "<string>",
                "nameInGroup": "Step 1",
                "randomizationUnits": [
                  "user"
                ],
                "analysisUnits": [
                  "user"
                ]
              }
            ],
            "analysisType": "mean",
            "analysisUnit": "user"
          }
        ],
        "layerSnapshot": {
          "key": "checkout-flow",
          "name": "Checkout Flow",
          "reservationPercent": 10,
          "otherReservationPercent": 70
        },
        "covariateInfo": {
          "id": "74a49a2b-4834-4246-917e-5d85231d8c2a",
          "fileName": "covariate.csv",
          "createdAt": "1654104600000"
        }
      }
    ],
    "analysisConfig": {
      "bayesianThreshold": "<string>",
      "significanceThreshold": "<string>",
      "testDirection": "<string>",
      "multipleComparisonCorrectionMethod": "bonferroni",
      "multipleComparisonCorrectionScope": "variations",
      "sequentialTestingEnabled": true
    },
    "mutableFieldsByStatus": {
      "not_started": {},
      "running": {},
      "stopped": {}
    }
  },
  "description": "<string>",
  "experiments": [
    {
      "key": "<string>",
      "name": "<string>",
      "environment": "<string>"
    }
  ]
}

{
  "code": "invalid_request",
  "message": "Invalid request body"
}

{
  "code": "unauthorized",
  "message": "Invalid access token"
}

{
  "code": "forbidden",
  "message": "Forbidden. Access to the requested resource was denied."
}

{
  "code": "not_found",
  "message": "Invalid resource identifier"
}

{
  "code": "rate_limited",
  "message": "You've exceeded the API rate limit. Try again later."
}

Authorizations

Authorization

string

header

required

Path Parameters

projectKey

string<string>

required

The project key

environmentKey

string<string>

required

The environment key

holdoutKey

string<string>

required

The holdout key

Body

application/json

instructions

object[]

required

The instructions to perform when updating. This should be an array with objects that look like {"kind": "update_action"}. Some instructions also require a value field in the array element.

Show child attributes

Example:

"[{\"kind\": \"updateName\", \"name\": \"Updated holdout name\"}]"

comment

string

Optional comment describing the update

Example:

"Optional comment"

Response

Holdout response

_id

string

required

status

enum<string>

required

Available options:

created,

enabled,

running,

ended

holdoutAmount

string

required

The percentage of traffic allocated to this holdout.

createdAt

integer<int64>

required

updatedAt

integer<int64>

required

baseExperiment

object

required

Show child attributes

description

string

experiments

object[]

Show child attributes