Update a holdout experiment using JSON Patch (RFC 6902) operations.\nSupports status transitions, configuration updates, and target changes.
\nAuthorization:
\nHOLDOUTS_ACCESS permission (feature-level gate)FLAGS_ADMIN permission on ALL affected projects (both old and new targets)holdouts-m2 feature flagOptimistic Locking:
\nIf-Match header with current revision ETag to prevent concurrent updatesSupported Operations:
\nValidation Rules:
\nETag value from previous GET request, used for optimistic locking.\nFormat: \"revision-{N}\" where N is the holdout's revision number.\nIf provided and does not match current revision, returns 409 Conflict.
", "pattern": "^\"revision-[0-9]+\"$" } ], "queryParameters": [], "bodyDataParameters": [], "formDataParameters": [], "oAuthParameters": [ { "id": "apiKey", "name": "apiKey", "kind": "optional", "type": "http", "scheme": "bearer" }, { "id": "OAuth2", "name": "OAuth2", "kind": "optional", "type": "oauth2", "description": "Write applications that authenticate with the REST API via OAuth 2.0.", "oauth2Flows": { "authorizationCode": { "authorizationUrl": "https://app.optimizely.com/oauth2/authorize", "tokenUrl": "https://app.optimizely.com/oauth2/token", "scopes": { "all": "Grants all access" } } }, "requiredScopes": [ "read", "write" ] } ], "cookieParameters": [] }, "responses": [ { "statusCode": "200", "description": "Holdout successfully updated", "jsonExample": "", "isExpanded": true, "headers": [ { "kind": "optional", "name": "ETag", "type": "string", "example": "\"revision-6\"", "description": "Current revision ETag for optimistic locking" } ], "schema": [ { "kind": "optional", "type": "object", "example": "{\"archived\":false,\"audience_conditions\":[\"or\",{\"audience_id\":5340810295}],\"created_by_user_email\":\"user@company.com\",\"created_time\":\"2023-12-15T10:00:00.000Z\",\"description\":\"Holdout group to measure the overall impact of our growth experiments throughout the year\",\"environment_key\":\"production\",\"holdout_results_api_token\":\"SampleToken.eyJhbGciOiJIUzI1NiIsInR5cCI6IkpXVCJ9\",\"id\":12345,\"key\":\"annual_growth_holdout\",\"metrics\":[{\"aggregator\":\"unique\",\"display_title\":\"Conversion Rate\",\"scope\":\"visitor\",\"winning_direction\":\"increasing\"}],\"name\":\"Annual Growth Control Group\",\"project_id\":98765,\"revision\":3,\"scope\":\"global\",\"start_time\":\"2024-01-01T00:00:00.000Z\",\"status\":\"running\",\"traffic_allocation\":1000,\"updated_time\":\"2024-01-01T10:00:00.000Z\",\"urn\":\"holdout.flag.optimizely.com::12345\"}", "description": "Represents a holdout experiment that reserves a portion of traffic to measure the impact of feature flags and experiments.
\nHoldouts help establish control groups by excluding a percentage of users from seeing any experiments, allowing you to measure the overall impact of your experimentation program against a baseline.
", "customType": "Holdout", "schema": [ { "name": "archived", "kind": "optional", "type": "boolean", "description": "Whether the holdout is archived. Archived holdouts are hidden from normal views\nbut retain their historical data and configuration.\n", "example": false }, { "name": "audience_conditions", "kind": "optional", "type": "array", "description": "Defines which audiences this holdout applies to. If omitted, the holdout applies to all users.\nUses logical operators like 'and', 'or', 'not' to combine multiple audience conditions.
", "example": "[\"[\"or\",{\"audience_id\":5340810295},{\"audience_id\":1234567890}]\"]", "itemType": "object", "customType": "object[]", "itemExample": "[\"or\",{\"audience_id\":5340810295},{\"audience_id\":1234567890}]", "itemDefault": "" }, { "name": "audience_ids", "kind": "optional", "type": "array", "deprecated": true, "description": "Warning: Deprecated\nDEPRECATED: Use audience_conditions instead. List of audience IDs that this holdout applies to.\nThis field is maintained for backward compatibility.
", "example": "[5340810295,1234567890]", "itemType": "integer", "customType": "integer[]", "itemExample": "", "itemDefault": "" }, { "name": "created_by_user_email", "kind": "optional", "type": "string", "readOnly": true, "description": "Email address of the user who created the holdout.", "example": "user@company.com" }, { "name": "created_time", "kind": "optional", "type": "stringThe environment where this holdout is active (e.g., 'production', 'staging').\nThe holdout only affects traffic in this specific environment.
", "example": "production" }, { "name": "environment_name", "kind": "optional", "type": "string", "readOnly": true, "description": "The human-readable name of the environment where this holdout is active.
", "example": "Production" }, { "name": "exclude_targeted_deliveries", "kind": "optional", "type": "boolean", "description": "When true, Targeted Delivery rules are excluded from this holdout, so\nholdout users are not withheld from them. Targeted Deliveries represent\npermanent ship decisions rather than active experiments, so there is\nnothing to measure by withholding them.\nApplies to global holdouts only; ignored for local holdouts.\nCan only be changed while the holdout is in draft status.\nDefaults to false.
", "example": false, "default": false }, { "name": "holdout_results_api_token", "kind": "optional", "type": "string", "readOnly": true, "description": "API token for accessing holdout results and analytics data.\nThis token is dynamically generated for each API response and provides\nsecure access to holdout-specific results endpoints.
", "example": "SampleToken.eyJhbGciOiJIUzI1NiIsInR5cCI6IkpXVCJ9" }, { "name": "id", "kind": "required", "type": "integer", "readOnly": true, "description": "System-generated unique identifier for the holdout.
", "example": 12345 }, { "name": "key", "kind": "required", "type": "string", "description": "Unique user-defined identifier for the holdout within the project.\nMust contain only alphanumeric characters, underscores, and hyphens.
", "example": "annual_growth_holdout", "maxLength": 64, "pattern": "^[a-zA-Z0-9_\\-]+$" }, { "name": "metrics", "kind": "optional", "type": "array", "description": "List of metrics being tracked and analyzed for this holdout.\nThese metrics help measure the impact of experiments on the control group.\n", "modelRef": "#/components/schemas/Metric", "customType": "Metric[]", "schema": [ { "name": "aggregator", "kind": "required", "type": "stringThe 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
", "enum": [ "unique", "count", "sum", "ratio" ] }, { "name": "display_title", "kind": "optional", "type": "string", "description": "An optional title for the unique metric configuration. If not provided, the event name will be used.
" }, { "name": "display_unit", "kind": "optional", "type": "string", "description": "An optional name for the unit of the unique metric configuration." }, { "name": "event_id", "kind": "optional", "type": "integerThe ID for the Event to select data from. Omitted for global metrics that are not relative to a specific Event, i.e. \"overall revenue\"
", "example": 32334454244, "format": "int64" }, { "name": "event_properties", "kind": "optional", "type": "object", "description": "", "example": "", "schema": [ { "name": "filter", "kind": "optional", "type": "object", "description": "", "example": "", "schema": [ { "name": "combine_operator", "kind": "optional", "type": "stringThe field to aggregate for the numerator of the metric. Required when 'aggregator' = 'sum', otherwise omitted
", "enum": [ "revenue", "value" ] }, { "name": "id", "kind": "optional", "type": "string", "description": "A unique identifier for the metric configuration." }, { "name": "metrics", "kind": "optional", "type": "array", "description": "", "modelRef": "#/components/schemas/SubMetric", "customType": "SubMetric[]", "schema": [ { "name": "aggregator", "kind": "optional", "type": "string", "description": "" }, { "name": "display_title", "kind": "optional", "type": "string", "nullable": true, "description": "" }, { "name": "event_id", "kind": "optional", "type": "integer", "description": "" }, { "name": "event_type", "kind": "optional", "type": "string", "description": "" }, { "name": "field", "kind": "optional", "type": "string", "nullable": true, "description": "" }, { "name": "role", "kind": "optional", "type": "stringSpecifies 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
", "enum": [ "session", "visitor", "event" ] }, { "name": "visibility", "kind": "optional", "type": "stringHuman-readable name for the holdout displayed in the UI.
", "example": "Annual Growth Control Group", "maxLength": 255 }, { "name": "project_id", "kind": "optional", "type": "integerProject objects returned by cross-project GET endpoints.\nFor global-scope holdouts, lists target project IDs.\nEmpty array for local-scope holdouts.\nFrontend resolves project names via entity-management API.
", "example": "[{\"id\":123}]", "itemType": "object", "customType": "object[]", "schema": [ { "name": "id", "kind": "optional", "type": "integerEnriched rule objects returned by cross-project GET endpoints.\nFor local-scope holdouts, lists target rules with metadata.\nEmpty array for global-scope holdouts.
", "example": "[{\"flag_key\":\"my_flag\",\"id\":456,\"key\":\"experiment_rule_a\",\"name\":\"Experiment Rule A\",\"project_id\":123}]", "itemType": "object", "customType": "object[]", "schema": [ { "name": "flag_id", "kind": "optional", "type": "integerDefines the scope of the holdout:
\nCurrent operational status of the holdout:
\nPercentage of traffic allocated to this holdout, expressed in basis points (1/100th of a percent).\nFor example: 100 = 1%, 1000 = 10%, 5000 = 50%. The remaining traffic sees experiments normally.
", "example": 1000, "minimum": 0, "maximum": 10000 }, { "name": "updated_time", "kind": "optional", "type": "stringRESTful link to fetch this holdout's details.\nFor project-scoped endpoints: /projects/{project_id}/holdouts/{holdout_id}\nFor cross-project endpoints: /holdouts/{holdout_id}
", "example": "/holdouts/12345" }, { "name": "urn", "kind": "optional", "type": "string", "readOnly": true, "description": "Universal Resource Name (URN) for the holdout, used for global identification.
", "example": "holdout.flag.optimizely.com::12345" } ], "modelRef": "#/components/schemas/Holdout", "isExpanded": true } ] }, { "statusCode": "400", "description": "Malformed requests and invalid parameter names and types", "jsonExample": "", "isExpanded": true }, { "statusCode": "401", "description": "Invalid credentials", "jsonExample": "", "isExpanded": true }, { "statusCode": "403", "description": "Do not have permission to perform the operation", "jsonExample": "", "isExpanded": true }, { "statusCode": "404", "description": "Not found. No content", "jsonExample": "", "isExpanded": true }, { "statusCode": "409", "description": "Conflict - concurrent modification detected (optimistic lock failure)
", "jsonExample": "", "isExpanded": true } ], "hasXCodeSamples": false, "examples": { "languages": [ { "id": "_HNAbGDEgeOBWlcXM8bUH", "language": "curl", "label": "cURL", "code": "curl --request PATCH \\\n --url https://api.optimizely.com/flags/v1//holdouts/{holdout_id} \\\n --header 'accept: application/json'" }, { "id": "LdF54nsuwcZf5kA7VMe-A", "language": "javascript", "label": "javascript", "code": "var myHeaders = new Headers();\nmyHeaders.append(\"accept\", \"application/json\");\nmyHeaders.append(\"content-type\", \"application/json-patch+json\");\n\nvar requestOptions = {\n method: 'PATCH',\n headers: myHeaders,\n redirect: 'follow'\n};\n\nfetch(\"https://api.optimizely.com/flags/v1//holdouts/{holdout_id}\", requestOptions)\n .then(response => response.text())\n .then(result => console.log(result))\n .catch(error => console.log('error', error));" }, { "id": "MIxeKEAXHrfk4JuuJ6fRR", "language": "ruby", "label": "Ruby", "code": "require \"uri\"\nrequire \"json\"\nrequire \"net/http\"\n\nurl = URI(\"https://api.optimizely.com/flags/v1//holdouts/{holdout_id}\")\n\nhttps = Net::HTTP.new(url.host, url.port)\nhttps.use_ssl = true\n\nrequest = Net::HTTP::Patch.new(url)\nrequest[\"accept\"] = \"application/json\"\nrequest[\"content-type\"] = \"application/json-patch+json\"\n\nresponse = https.request(request)\nputs response.read_body\n" }, { "id": "M29FV5E0JBHw4j7n7pChn", "language": "python", "label": "Python", "code": "import requests\nimport json\n\nurl = \"https://api.optimizely.com/flags/v1//holdouts/{holdout_id}\"\n\npayload = {}\nheaders = {\n 'accept': 'application/json',\n 'content-type': 'application/json-patch+json'\n}\n\nresponse = requests.request(\"PATCH\", url, headers=headers, data=payload)\n\nprint(response.text)\n" } ], "selectedLanguageId": "_HNAbGDEgeOBWlcXM8bUH" }, "results": { "languages": [ { "id": "BkSVX2O5fR-VJHRS3_Wis", "language": "200", "code": "// Holdout successfully updated\n{\n \"archived\": false,\n \"audience_conditions\": [\n {}\n ],\n \"audience_ids\": [\n 0\n ],\n \"created_by_user_email\": \"user@company.com\",\n \"created_time\": \"2023-12-15T10:00:00.000Z\",\n \"description\": \"Holdout group to measure the overall impact of our growth experiments throughout the year\",\n \"end_time\": \"2024-12-31T23:59:59.000Z\",\n \"environment_key\": \"production\",\n \"environment_name\": \"Production\",\n \"exclude_targeted_deliveries\": false,\n \"holdout_results_api_token\": \"SampleToken.eyJhbGciOiJIUzI1NiIsInR5cCI6IkpXVCJ9\",\n \"id\": 12345,\n \"key\": \"annual_growth_holdout\",\n \"metrics\": [\n {\n \"aggregator\": \"\",\n \"display_title\": \"\",\n \"display_unit\": \"\",\n \"event_id\": 32334454244,\n \"event_properties\": {\n \"filter\": {\n \"combine_operator\": \"\",\n \"conditions\": [\n {\n \"name\": \"\",\n \"operator\": \"\",\n \"type\": \"\",\n \"value\": \"\"\n }\n ]\n }\n },\n \"event_type\": \"\",\n \"field\": \"\",\n \"id\": \"\",\n \"metrics\": [\n {\n \"aggregator\": \"\",\n \"display_title\": \"\",\n \"event_id\": 0,\n \"event_type\": \"\",\n \"field\": \"\",\n \"role\": \"\",\n \"scope\": \"\"\n }\n ],\n \"project_id\": 0,\n \"scope\": \"\",\n \"visibility\": \"\",\n \"winning_direction\": \"\"\n }\n ],\n \"name\": \"Annual Growth Control Group\",\n \"project_id\": 98765,\n \"projects\": [\n {\n \"id\": \"\"\n }\n ],\n \"revision\": 3,\n \"rules\": [\n {\n \"flag_id\": \"\",\n \"flag_key\": \"\",\n \"flag_name\": \"\",\n \"id\": \"\",\n \"key\": \"\",\n \"name\": \"\",\n \"project_id\": \"\"\n }\n ],\n \"scope\": \"global\",\n \"start_time\": \"2024-01-01T00:00:00.000Z\",\n \"status\": \"running\",\n \"traffic_allocation\": 1000,\n \"updated_time\": \"2024-01-01T10:00:00.000Z\",\n \"url\": \"/holdouts/12345\",\n \"urn\": \"holdout.flag.optimizely.com::12345\"\n}" }, { "id": "lSyllBXNBQJzFdfexouxV", "language": "400", "code": "// Malformed requests and invalid parameter names and types\n" }, { "id": "ShyAxnFbA3IvJy_iu9xRo", "language": "401", "code": "// Invalid credentials\n" }, { "id": "fRa5pYyS37oCEMekAhQvK", "language": "403", "code": "// Do not have permission to perform the operation\n" }, { "id": "Y9j-9eKhCuUviMl-Icd6I", "language": "404", "code": "// Not found. No content\n" }, { "id": "jj268vGQuvAW4XVM4ctGZ", "language": "409", "code": "// Conflict - concurrent modification detected (optimistic lock failure)\n" } ], "selectedLanguageId": "BkSVX2O5fR-VJHRS3_Wis" } }, "children": [ { "text": "" } ] }