The availability of features may depend on your plan type. Contact your Customer Success Manager if you have any questions.
Dev guideRecipesAPI ReferenceChangelog
Dev guideAPI ReferenceRecipesChangelogUser GuideGitHubDev CommunityOptimizely AcademySubmit a ticketLog In
API Reference

Update a Holdout using JSON Patch

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.

Supported Operations:

  • Status transitions: Move holdouts through their lifecycle (draftrunningconcluded)
  • Configuration updates: Modify traffic allocation, name, description, and other settings
  • Archive management: Archive/unarchive concluded holdouts
  • Metrics updates: Modify metric configurations (restricted based on status)

State Management & Validation Rules:

  • Draft holdouts: All fields can be updated except readonly properties
  • Running holdouts: Limited updates allowed; cannot modify metrics or core configuration
  • Concluded holdouts: Only name and archived status can be modified
  • Status transitions: Must follow proper sequence (draft→running→concluded)
  • Traffic allocation: Must be 0-10000 basis points (0-100%)

Automatic Timestamp Management:

  • Moving to running status automatically sets start_time to current timestamp
  • Moving to concluded status automatically sets end_time to current timestamp

Common Update Patterns:

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

Important Limitations:

  • Cannot modify metrics on running holdouts (prevents mid-experiment changes)
  • Cannot archive non-concluded holdouts (must conclude first)
  • Cannot update core configuration on running/concluded holdouts
  • ReadOnly properties in patch operations are ignored
Recent Requests
Log in to see full request history
TimeStatusUser Agent
Retrieving recent requests…
LoadingLoading…
Path Params
integer
required

The project identifier

integer
required

The holdout identifier

Body Params

Array of JSON Patch operations to apply to the holdout. Each operation specifies a change to make to the holdout resource.

Supported patch paths include:

  • /name - Update holdout display name
  • /description - Update holdout description
  • /status - Change holdout status (draft/running/concluded)
  • /traffic_allocation - Update traffic percentage (0-10000 basis points)
  • /archived - Archive or unarchive the holdout
  • /metrics - Update metric configurations (not allowed on running holdouts)

Note: Status transitions and archiving have specific validation rules enforced server-side.

Headers
string
enum
Defaults to application/json

Generated from available response content types

Allowed:
Responses

404

Not found. No content

Language
Credentials
LoadingLoading…
Response
Click Try It! to start a request and see the response here! Or choose an example:
application/json
application/problem+json