--- title: Update a Holdout using JSON Patch slug: feature-experimentation/api/update-a-holdout-using-json-patch docTags: createdAt: 2026-08-28T15:54:06.731Z --- { "id": "p2Yho2M5OuiePm7hTV_qh", "type": "api-oas-v2", "data": { "method": "POST", "url": "https://api.optimizely.com/flags/v1//projects/{project_id}/holdouts/{holdout_id}", "servers": [ { "url": "https://api.optimizely.com/flags/v1//projects/{project_id}/holdouts/{holdout_id}" } ], "name": "Update a Holdout using JSON Patch", "description": "

Updates a specific holdout using JSON Patch operations (RFC 6902). This endpoint allows you to modify individual properties of an existing holdout without replacing the entire resource.

\n

Supported Operations:

\n\n

State Management & Validation Rules:

\n\n

Automatic Timestamp Management:

\n\n

Common Update Patterns:

\n
[\n  {\"op\": \"replace\", \"path\": \"/name\", \"value\": \"Updated Holdout Name\"},\n  {\"op\": \"replace\", \"path\": \"/traffic_allocation\", \"value\": 1500},\n  {\"op\": \"replace\", \"path\": \"/status\", \"value\": \"running\"}\n]\n
\n

Important Limitations:

\n", "contentType": "application/json-patch+json", "request": { "pathParameters": [ { "kind": "required", "name": "project_id", "type": "integer", "example": 12345, "description": "The project identifier" }, { "kind": "required", "name": "holdout_id", "type": "integer", "example": 54321, "description": "The holdout identifier" } ], "headerParameters": [ { "name": "accept", "type": "string", "kind": "optional", "description": "Generated from available response content types", "enum": [ "application/json" ], "default": "application/json" } ], "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": "

Successful update of the holdout. Returns the updated holdout resource with all modifications applied.

\n

Response Details:

\n\n

Status-Specific Behavior:

\n", "jsonExample": "", "isExpanded": true, "subExamples": [ { "label": "GENERATED", "code": "// Successful update of the holdout. Returns the updated holdout resource with all modifications applied.\nResponse Details:\n\nContains the complete updated holdout with all applied changes\nIncludes RESTful JSON (https://restfuljson.org/) styled links for related actions\nAutomatic timestamps are included (start_time/end_time) if status was changed\nMissing links indicate insufficient permissions for related operations\nReadOnly fields reflect any server-managed updates (like timestamps)\n\nStatus-Specific Behavior:\n\nDraft→Running: Includes newly set start_time\nRunning→Concluded: Includes newly set end_time\nArchived: Shows archived: true with preserved historical data\n{}" }, { "label": "basic_update", "code": "// Updated holdout with new name and traffic\n{\n \"987\": {\n \"archive_url\": \"/projects/12345/holdouts/archived\",\n \"archived\": false,\n \"created_time\": \"2019-05-08T00:00:00.000Z\",\n \"delete_url\": \"/projects/12345/holdouts/987\",\n \"description\": \"Updated control group for better targeting\",\n \"environment_key\": \"production\",\n \"holdout_results_api_token\": \"SampleToken.eyJhbGciOiJIUzI1NiIsInR5cCI6IkpXVCJ9\",\n \"id\": 987,\n \"name\": \"Updated Control Group\",\n \"project_id\": 12345,\n \"rules\": {\n \"456\": {\n \"created_time\": \"2022-01-08T00:00:00.000Z\",\n \"flag_key\": \"recurring_revenue\",\n \"flag_name\": \"Recurring Revenue\",\n \"flag_status\": \"unarchived\",\n \"rule_key\": \"experiment_one\",\n \"rule_name\": \"Experiment One\",\n \"traffic_allocation\": 2000,\n \"updated_time\": \"2022-01-08T00:00:00.000Z\"\n }\n },\n \"status\": \"draft\",\n \"traffic_allocation\": 2500,\n \"unarchive_url\": \"/projects/12345/holdouts/unarchived\",\n \"update_url\": \"/projects/12345/holdouts/987\",\n \"updated_time\": \"2024-09-16T10:30:00.000Z\",\n \"url\": \"/projects/12345/holdouts/987\",\n \"urn\": \"holdouts.flag.optimizely.com::987\"\n }\n}" }, { "label": "started_holdout", "code": "// Holdout moved to running status\n{\n \"987\": {\n \"archived\": false,\n \"created_time\": \"2019-05-08T00:00:00.000Z\",\n \"delete_url\": \"/projects/12345/holdouts/987\",\n \"description\": \"Now actively excluding traffic from experiments\",\n \"environment_key\": \"production\",\n \"holdout_results_api_token\": \"SampleToken.eyJhbGciOiJIUzI1NiIsInR5cCI6IkpXVCJ9\",\n \"id\": 987,\n \"name\": \"Live Control Group\",\n \"project_id\": 12345,\n \"start_time\": \"2024-09-16T10:30:00.000Z\",\n \"status\": \"running\",\n \"traffic_allocation\": 1500,\n \"update_url\": \"/projects/12345/holdouts/987\",\n \"updated_time\": \"2024-09-16T10:30:00.000Z\",\n \"url\": \"/projects/12345/holdouts/987\",\n \"urn\": \"holdouts.flag.optimizely.com::987\"\n }\n}" } ], "schema": [ { "kind": "optional", "type": "object", "example": "{\"987\":{\"archive_url\":\"/projects/12345/holdouts/archived\",\"archived\":false,\"created_time\":\"2019-05-08T00:00:00.000Z\",\"delete_url\":\"/projects/12345/holdouts/987\",\"description\":\"Updated control group for better targeting\",\"environment_key\":\"production\",\"holdout_results_api_token\":\"SampleToken.eyJhbGciOiJIUzI1NiIsInR5cCI6IkpXVCJ9\",\"id\":987,\"name\":\"Updated Control Group\",\"project_id\":12345,\"rules\":{\"456\":{\"created_time\":\"2022-01-08T00:00:00.000Z\",\"flag_key\":\"recurring_revenue\",\"flag_name\":\"Recurring Revenue\",\"flag_status\":\"unarchived\",\"rule_key\":\"experiment_one\",\"rule_name\":\"Experiment One\",\"traffic_allocation\":2000,\"updated_time\":\"2022-01-08T00:00:00.000Z\"}},\"status\":\"draft\",\"traffic_allocation\":2500,\"unarchive_url\":\"/projects/12345/holdouts/unarchived\",\"update_url\":\"/projects/12345/holdouts/987\",\"updated_time\":\"2024-09-16T10:30:00.000Z\",\"url\":\"/projects/12345/holdouts/987\",\"urn\":\"holdouts.flag.optimizely.com::987\"}}", "examples": [ { "label": "Updated holdout with new name and traffic", "value": "{\"987\":{\"archive_url\":\"/projects/12345/holdouts/archived\",\"archived\":false,\"created_time\":\"2019-05-08T00:00:00.000Z\",\"delete_url\":\"/projects/12345/holdouts/987\",\"description\":\"Updated control group for better targeting\",\"environment_key\":\"production\",\"holdout_results_api_token\":\"SampleToken.eyJhbGciOiJIUzI1NiIsInR5cCI6IkpXVCJ9\",\"id\":987,\"name\":\"Updated Control Group\",\"project_id\":12345,\"rules\":{\"456\":{\"created_time\":\"2022-01-08T00:00:00.000Z\",\"flag_key\":\"recurring_revenue\",\"flag_name\":\"Recurring Revenue\",\"flag_status\":\"unarchived\",\"rule_key\":\"experiment_one\",\"rule_name\":\"Experiment One\",\"traffic_allocation\":2000,\"updated_time\":\"2022-01-08T00:00:00.000Z\"}},\"status\":\"draft\",\"traffic_allocation\":2500,\"unarchive_url\":\"/projects/12345/holdouts/unarchived\",\"update_url\":\"/projects/12345/holdouts/987\",\"updated_time\":\"2024-09-16T10:30:00.000Z\",\"url\":\"/projects/12345/holdouts/987\",\"urn\":\"holdouts.flag.optimizely.com::987\"}}" }, { "label": "Holdout moved to running status", "value": "{\"987\":{\"archived\":false,\"created_time\":\"2019-05-08T00:00:00.000Z\",\"delete_url\":\"/projects/12345/holdouts/987\",\"description\":\"Now actively excluding traffic from experiments\",\"environment_key\":\"production\",\"holdout_results_api_token\":\"SampleToken.eyJhbGciOiJIUzI1NiIsInR5cCI6IkpXVCJ9\",\"id\":987,\"name\":\"Live Control Group\",\"project_id\":12345,\"start_time\":\"2024-09-16T10:30:00.000Z\",\"status\":\"running\",\"traffic_allocation\":1500,\"update_url\":\"/projects/12345/holdouts/987\",\"updated_time\":\"2024-09-16T10:30:00.000Z\",\"url\":\"/projects/12345/holdouts/987\",\"urn\":\"holdouts.flag.optimizely.com::987\"}}" } ], "description": "

A dictionary/map of holdouts where each key is the holdout ID and the value is the holdout object.

\n

This structure is used internally for efficient lookups and when representing holdout\nrelationships. The keys are string representations of holdout IDs.

", "customType": "HoldoutMap", "schema": [], "modelRef": "#/components/schemas/HoldoutMap", "isExpanded": true } ] }, { "statusCode": "400", "description": "

Bad Request - Invalid patch operations, validation failures, or illegal state transitions.

\n

Common causes:

\n", "jsonExample": "", "isExpanded": true, "subExamples": [ { "label": "GENERATED", "code": "// Bad Request - Invalid patch operations, validation failures, or illegal state transitions.\nCommon causes:\n\nInvalid state transitions: Attempting invalid status changes (e.g., draft→concluded)\nRestricted updates: Trying to modify metrics on running holdouts\nInvalid traffic allocation: Values outside 0-10000 range\nArchive violations: Attempting to archive non-concluded holdouts\nMalformed patch: Invalid JSON Patch structure or unsupported operations\nMissing required fields: Patch operations targeting required fields with null/empty values\nType mismatches: Providing wrong data types for specific fields\n{\n \"detail\": \"\",\n \"status\": 0,\n \"title\": \"\",\n \"type\": \"\",\n \"uuid\": \"\"\n}" }, { "label": "concluded_holdout_restriction", "code": "// Limited updates on concluded holdout\n{\n \"detail\": \"Can't edit holdouts in 'concluded' state.\",\n \"status\": 400,\n \"title\": \"Unable to update holdout\",\n \"type\": \"about:blank\"\n}" }, { "label": "invalid_state_transition", "code": "// Invalid status transition\n{\n \"detail\": \"Holdout with key 'control_group' is not in 'draft' state, can't move to 'running' state.\",\n \"status\": 400,\n \"title\": \"Unable to update holdout\",\n \"type\": \"about:blank\"\n}" }, { "label": "invalid_traffic_allocation", "code": "// Traffic allocation out of range\n{\n \"detail\": \"Traffic allocation must be between 0 and 10000 (basis points).\",\n \"status\": 400,\n \"title\": \"Unable to update holdout\",\n \"type\": \"about:blank\"\n}" }, { "label": "metrics_update_restricted", "code": "// Cannot update metrics on running holdout\n{\n \"detail\": \"Can't update metrics on a running holdout.\",\n \"status\": 400,\n \"title\": \"Unable to update holdout\",\n \"type\": \"about:blank\"\n}" } ], "schema": [ { "kind": "optional", "type": "object", "example": "{\"detail\":\"Can't edit holdouts in 'concluded' state.\",\"status\":400,\"title\":\"Unable to update holdout\",\"type\":\"about:blank\"}", "examples": [ { "label": "Limited updates on concluded holdout", "value": "{\"detail\":\"Can't edit holdouts in 'concluded' state.\",\"status\":400,\"title\":\"Unable to update holdout\",\"type\":\"about:blank\"}" }, { "label": "Invalid status transition", "value": "{\"detail\":\"Holdout with key 'control_group' is not in 'draft' state, can't move to 'running' state.\",\"status\":400,\"title\":\"Unable to update holdout\",\"type\":\"about:blank\"}" }, { "label": "Traffic allocation out of range", "value": "{\"detail\":\"Traffic allocation must be between 0 and 10000 (basis points).\",\"status\":400,\"title\":\"Unable to update holdout\",\"type\":\"about:blank\"}" }, { "label": "Cannot update metrics on running holdout", "value": "{\"detail\":\"Can't update metrics on a running holdout.\",\"status\":400,\"title\":\"Unable to update holdout\",\"type\":\"about:blank\"}" } ], "description": "

https://tools.ietf.org/html/rfc7807#section-3.1

", "customType": "ProblemDetail", "schema": [ { "name": "detail", "kind": "required", "type": "string", "description": "

A human-readable explanation specific to this occurrence of the problem.

" }, { "name": "status", "kind": "required", "type": "integer", "description": "

The HTTP status code ([RFC7231], Section 6) generated by the origin server for this occurrence of the problem.

" }, { "name": "title", "kind": "required", "type": "string", "description": "

A short, human-readable summary of the problem type.

" }, { "name": "type", "kind": "required", "type": "string", "description": "

A URI reference [RFC3986] that identifies the problem type. Contains 'about

' if unspecified.

" }, { "name": "uuid", "kind": "optional", "type": "string", "description": "Error reference for customer support" } ], "modelRef": "#/components/schemas/ProblemDetail", "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": "Conflicting resource state with requested action", "jsonExample": "", "isExpanded": true } ], "hasXCodeSamples": false, "examples": { "languages": [ { "id": "dYe6q-6jcy4xIsvPkd_A_", "language": "curl", "label": "cURL", "code": "curl --request POST \\\n --url https://api.optimizely.com/flags/v1//projects/{project_id}/holdouts/{holdout_id} \\\n --header 'accept: application/json'" }, { "id": "bnAGVmsRpAzu9Wspg1sNP", "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: 'POST',\n headers: myHeaders,\n redirect: 'follow'\n};\n\nfetch(\"https://api.optimizely.com/flags/v1//projects/{project_id}/holdouts/{holdout_id}\", requestOptions)\n .then(response => response.text())\n .then(result => console.log(result))\n .catch(error => console.log('error', error));" }, { "id": "jLnbjZuHlQr-oJ2jwAcQr", "language": "ruby", "label": "Ruby", "code": "require \"uri\"\nrequire \"json\"\nrequire \"net/http\"\n\nurl = URI(\"https://api.optimizely.com/flags/v1//projects/{project_id}/holdouts/{holdout_id}\")\n\nhttps = Net::HTTP.new(url.host, url.port)\nhttps.use_ssl = true\n\nrequest = Net::HTTP::Post.new(url)\nrequest[\"accept\"] = \"application/json\"\nrequest[\"content-type\"] = \"application/json-patch+json\"\n\nresponse = https.request(request)\nputs response.read_body\n" }, { "id": "uYQhDP4E3Zupr1RiHjPPV", "language": "python", "label": "Python", "code": "import requests\nimport json\n\nurl = \"https://api.optimizely.com/flags/v1//projects/{project_id}/holdouts/{holdout_id}\"\n\npayload = {}\nheaders = {\n 'accept': 'application/json',\n 'content-type': 'application/json-patch+json'\n}\n\nresponse = requests.request(\"POST\", url, headers=headers, data=payload)\n\nprint(response.text)\n" } ], "selectedLanguageId": "dYe6q-6jcy4xIsvPkd_A_" }, "results": { "languages": [ { "id": "response-0-200", "language": "200", "code": "// Successful update of the holdout. Returns the updated holdout resource with all modifications applied.\nResponse Details:\n\nContains the complete updated holdout with all applied changes\nIncludes RESTful JSON (https://restfuljson.org/) styled links for related actions\nAutomatic timestamps are included (start_time/end_time) if status was changed\nMissing links indicate insufficient permissions for related operations\nReadOnly fields reflect any server-managed updates (like timestamps)\n\nStatus-Specific Behavior:\n\nDraft→Running: Includes newly set start_time\nRunning→Concluded: Includes newly set end_time\nArchived: Shows archived: true with preserved historical data\n{}", "subExamples": [ { "label": "GENERATED", "code": "// Successful update of the holdout. Returns the updated holdout resource with all modifications applied.\nResponse Details:\n\nContains the complete updated holdout with all applied changes\nIncludes RESTful JSON (https://restfuljson.org/) styled links for related actions\nAutomatic timestamps are included (start_time/end_time) if status was changed\nMissing links indicate insufficient permissions for related operations\nReadOnly fields reflect any server-managed updates (like timestamps)\n\nStatus-Specific Behavior:\n\nDraft→Running: Includes newly set start_time\nRunning→Concluded: Includes newly set end_time\nArchived: Shows archived: true with preserved historical data\n{}" }, { "label": "basic_update", "code": "// Updated holdout with new name and traffic\n{\n \"987\": {\n \"archive_url\": \"/projects/12345/holdouts/archived\",\n \"archived\": false,\n \"created_time\": \"2019-05-08T00:00:00.000Z\",\n \"delete_url\": \"/projects/12345/holdouts/987\",\n \"description\": \"Updated control group for better targeting\",\n \"environment_key\": \"production\",\n \"holdout_results_api_token\": \"SampleToken.eyJhbGciOiJIUzI1NiIsInR5cCI6IkpXVCJ9\",\n \"id\": 987,\n \"name\": \"Updated Control Group\",\n \"project_id\": 12345,\n \"rules\": {\n \"456\": {\n \"created_time\": \"2022-01-08T00:00:00.000Z\",\n \"flag_key\": \"recurring_revenue\",\n \"flag_name\": \"Recurring Revenue\",\n \"flag_status\": \"unarchived\",\n \"rule_key\": \"experiment_one\",\n \"rule_name\": \"Experiment One\",\n \"traffic_allocation\": 2000,\n \"updated_time\": \"2022-01-08T00:00:00.000Z\"\n }\n },\n \"status\": \"draft\",\n \"traffic_allocation\": 2500,\n \"unarchive_url\": \"/projects/12345/holdouts/unarchived\",\n \"update_url\": \"/projects/12345/holdouts/987\",\n \"updated_time\": \"2024-09-16T10:30:00.000Z\",\n \"url\": \"/projects/12345/holdouts/987\",\n \"urn\": \"holdouts.flag.optimizely.com::987\"\n }\n}" }, { "label": "started_holdout", "code": "// Holdout moved to running status\n{\n \"987\": {\n \"archived\": false,\n \"created_time\": \"2019-05-08T00:00:00.000Z\",\n \"delete_url\": \"/projects/12345/holdouts/987\",\n \"description\": \"Now actively excluding traffic from experiments\",\n \"environment_key\": \"production\",\n \"holdout_results_api_token\": \"SampleToken.eyJhbGciOiJIUzI1NiIsInR5cCI6IkpXVCJ9\",\n \"id\": 987,\n \"name\": \"Live Control Group\",\n \"project_id\": 12345,\n \"start_time\": \"2024-09-16T10:30:00.000Z\",\n \"status\": \"running\",\n \"traffic_allocation\": 1500,\n \"update_url\": \"/projects/12345/holdouts/987\",\n \"updated_time\": \"2024-09-16T10:30:00.000Z\",\n \"url\": \"/projects/12345/holdouts/987\",\n \"urn\": \"holdouts.flag.optimizely.com::987\"\n }\n}" } ] }, { "id": "response-1-400", "language": "400", "code": "// Bad Request - Invalid patch operations, validation failures, or illegal state transitions.\nCommon causes:\n\nInvalid state transitions: Attempting invalid status changes (e.g., draft→concluded)\nRestricted updates: Trying to modify metrics on running holdouts\nInvalid traffic allocation: Values outside 0-10000 range\nArchive violations: Attempting to archive non-concluded holdouts\nMalformed patch: Invalid JSON Patch structure or unsupported operations\nMissing required fields: Patch operations targeting required fields with null/empty values\nType mismatches: Providing wrong data types for specific fields\n{\n \"detail\": \"\",\n \"status\": 0,\n \"title\": \"\",\n \"type\": \"\",\n \"uuid\": \"\"\n}", "subExamples": [ { "label": "GENERATED", "code": "// Bad Request - Invalid patch operations, validation failures, or illegal state transitions.\nCommon causes:\n\nInvalid state transitions: Attempting invalid status changes (e.g., draft→concluded)\nRestricted updates: Trying to modify metrics on running holdouts\nInvalid traffic allocation: Values outside 0-10000 range\nArchive violations: Attempting to archive non-concluded holdouts\nMalformed patch: Invalid JSON Patch structure or unsupported operations\nMissing required fields: Patch operations targeting required fields with null/empty values\nType mismatches: Providing wrong data types for specific fields\n{\n \"detail\": \"\",\n \"status\": 0,\n \"title\": \"\",\n \"type\": \"\",\n \"uuid\": \"\"\n}" }, { "label": "concluded_holdout_restriction", "code": "// Limited updates on concluded holdout\n{\n \"detail\": \"Can't edit holdouts in 'concluded' state.\",\n \"status\": 400,\n \"title\": \"Unable to update holdout\",\n \"type\": \"about:blank\"\n}" }, { "label": "invalid_state_transition", "code": "// Invalid status transition\n{\n \"detail\": \"Holdout with key 'control_group' is not in 'draft' state, can't move to 'running' state.\",\n \"status\": 400,\n \"title\": \"Unable to update holdout\",\n \"type\": \"about:blank\"\n}" }, { "label": "invalid_traffic_allocation", "code": "// Traffic allocation out of range\n{\n \"detail\": \"Traffic allocation must be between 0 and 10000 (basis points).\",\n \"status\": 400,\n \"title\": \"Unable to update holdout\",\n \"type\": \"about:blank\"\n}" }, { "label": "metrics_update_restricted", "code": "// Cannot update metrics on running holdout\n{\n \"detail\": \"Can't update metrics on a running holdout.\",\n \"status\": 400,\n \"title\": \"Unable to update holdout\",\n \"type\": \"about:blank\"\n}" } ] }, { "id": "response-2-401", "language": "401", "code": "// Invalid credentials\n" }, { "id": "response-3-403", "language": "403", "code": "// Do not have permission to perform the operation\n" }, { "id": "response-4-404", "language": "404", "code": "// Not found. No content\n" }, { "id": "response-5-409", "language": "409", "code": "// Conflicting resource state with requested action\n" } ], "selectedLanguageId": "response-0-200" } }, "children": [ { "text": "" } ] }