Delete a Holdout

1 min

DELETE

https://api.optimizely.com/flags/v1//projects/{project_id}/holdouts/{holdout_id}

Permanently and irreversibly delete a holdout by its unique ID. This is a destructive operation that cannot be undone.

⚠️ CAUTION - Permanent Deletion:

All holdout configuration data will be permanently lost
Associated metric data will be deleted from MetricsHub
Experiment rules and historical data will be removed
There is no way to recover this data after deletion

What gets deleted:

Holdout configuration (traffic allocation, audience conditions, etc.)
All associated experiment rules and their settings
Metric tracking data and historical performance
System metadata and lifecycle timestamps

Safer Alternative - Archiving: If you want to stop a holdout without permanent data loss, consider archiving instead:

Update the holdout status to concluded (if currently running)
Use the PATCH endpoint to set archived: true

Archived holdouts preserve all historical data while removing them from active lists and preventing further modifications.

When to use DELETE vs ARCHIVE:

DELETE: Use only when you're certain the holdout and all its data should be permanently removed
ARCHIVE: Recommended for most cases - preserves data for analysis while cleaning up active experiments

Important Notes:

Can delete holdouts in any status (draft, running, concluded)
Operation affects both database and MetricsHub systems
This corresponds to the delete_url link in holdout responses

project_idintegerThe project identifier

holdout_idintegerThe holdout identifier

acceptstringGenerated from available response content types

204Successfully deleted the holdout. No response body is returned. Deletion completed: <ul> <li>Holdout configuration permanently removed from database</li> <li>Associated metrics deleted from MetricsHub</li> <li>All experiment rules and historical data destroyed</li> <li>Holdout is no longer accessible via any API endpoints</li> </ul> What happens after deletion: <ul> <li>GET requests to this holdout will return 404 Not Found</li> <li>The holdout will not appear in list responses</li> <li>Associated URLs (update_url, fetch_url, etc.) become invalid</li> <li>Any references to this holdout in other systems should be cleaned up</li> </ul> A successful 204 response confirms the holdout has been completely removed from all systems.

400Bad Request - Invalid request parameters or malformed holdout ID. Common causes: <ul> <li>Invalid <code>holdout_id</code> format (must be a positive integer)</li> <li>Invalid <code>project_id</code> format (must be a positive integer)</li> <li>Malformed request structure</li> </ul>

401Invalid credentials

403Forbidden - You don't have permission to delete holdouts in this project. Permission requirements: <ul> <li>Must have project-level access</li> <li>Must have holdout deletion permissions</li> <li>Holdouts feature must be enabled for this project</li> </ul> Common causes: <ul> <li>Insufficient user permissions for destructive operations</li> <li>Project-level permissions don't include holdout management</li> <li>Organization-level policies restrict holdout deletion</li> <li>Holdouts feature flag is disabled for this project</li> </ul>

404Not Found - The specified holdout does not exist or has already been deleted. Possible reasons: <ul> <li>Holdout ID does not exist in the specified project</li> <li>Project ID does not exist or you don't have access to it</li> <li>Holdout was already deleted by another user/process</li> <li>Insufficient permissions to view or delete this holdout</li> </ul> Note: This is also returned if the holdout exists but you lack delete permissions, for security reasons (to prevent ID enumeration attacks).

curl --request DELETE \
     --url https://api.optimizely.com/flags/v1//projects/{project_id}/holdouts/{holdout_id} \
     --header 'accept: application/json'