Delete a Holdout
1 min
DELETE
https://api.optimizely.com/flags/v1//projects/{project_id}/holdouts/{holdout_id}
project_idintegerThe project identifier
holdout_idintegerThe holdout identifier
acceptstringGenerated from available response content types
204<p>Successfully deleted the holdout. No response body is returned.</p>
<p><strong>Deletion completed:</strong></p>
<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>
<p><strong>What happens after deletion:</strong></p>
<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>
<p>A successful 204 response confirms the holdout has been completely removed from all systems.</p>
400<p>Bad Request - Invalid request parameters or malformed holdout ID.</p>
<p><strong>Common causes:</strong></p>
<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
403<p>Forbidden - You don't have permission to delete holdouts in this project.</p>
<p><strong>Permission requirements:</strong></p>
<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>
<p><strong>Common causes:</strong></p>
<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>
404<p>Not Found - The specified holdout does not exist or has already been deleted.</p>
<p><strong>Possible reasons:</strong></p>
<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>
<p><strong>Note</strong>: This is also returned if the holdout exists but you lack delete permissions,
for security reasons (to prevent ID enumeration attacks).</p>
curl --request DELETE \
--url https://api.optimizely.com/flags/v1//projects/{project_id}/holdouts/{holdout_id} \
--header 'accept: application/json'