Fetch experiments associated with a holdout

1 min

GET

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

Retrieves a list of experiments that are connected to a specific holdout through the system's data relationships.

What you'll get:

Experiment identification: Layer experiment IDs from connected rules
Timing information: Start and end times from experiment reports
Variation details: Deployed variation IDs when configured
Clean data: Filtered to remove empty or null values for clarity

How experiments connect to holdouts: This endpoint traverses complex database relationships to find experiments associated with a holdout:

Holdout → Project: Matches by project_id
Project → Flags: All flags in the same project
Flags → Rulesets → Rules: Rules within flag configurations
Rules → Reports: Experiment reports linked to rules
Rules → Variations: Deployed variations (when configured)

Data relationships explained:

Each returned experiment represents a rule that's potentially affected by the holdout's traffic allocation
Experiment timing comes from associated reports (start_time, end_time)
Deployed variations are included when rules have configured variations
Results are automatically filtered to exclude empty/null values

Use cases:

Impact analysis: Understanding which experiments are affected by a holdout
Experiment coordination: Viewing overlapping experiment timelines
Traffic allocation planning: Seeing experiment relationships before making holdout changes
Reporting integration: Connecting holdout data with experiment performance
Debugging: Investigating unexpected experiment behavior related to holdouts

Performance considerations:

Query involves multiple table joins across the experiment system
Results are processed to remove empty values for cleaner responses
Response size depends on the number of connected experiments

This endpoint provides crucial visibility into the complex relationships between holdouts and the experiments they may influence.

project_idintegerThe project identifier

holdout_idintegerThe holdout identifier

acceptstringGenerated from available response content types

200Successfully retrieved the list of experiments associated with the holdout. Response structure: <ul> <li>Returns an array of experiment objects</li> <li>Each experiment contains identification, timing, and variation data</li> <li>Empty or null values are automatically filtered out</li> <li>Results are ordered by the database query (typically by experiment_id)</li> </ul> Data interpretation: <ul> <li>experiment_id: References the layer_experiment_id from rules connected to this holdout</li> <li>Timing fields: Reflect actual experiment run periods from reports</li> <li>deployed_variation_id: Present only when experiments have specific variation deployments</li> <li>Missing end_time: Indicates ongoing or perpetually running experiments</li> <li>Missing deployed_variation_id: Experiments without specific variation targeting</li> </ul> Empty response scenarios: <ul> <li>Holdout exists but has no connected experiments (valid scenario)</li> <li>No rules in the project match the holdout's configuration</li> <li>All connected experiments have been archived or removed</li> </ul> Use this data for: <ul> <li>Understanding experiment overlap with holdout traffic</li> <li>Planning holdout changes with awareness of affected experiments</li> <li>Building experiment impact reports and analytics</li> <li>Coordinating experiment timelines and traffic allocation</li> </ul>

400Bad Request - Invalid request parameters or malformed IDs. 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 or unsupported query parameters</li> </ul>

401Invalid credentials

403Forbidden - You don't have permission to view holdout experiments in this project. Permission requirements: <ul> <li>Must have project-level read access</li> <li>Must have permissions to view holdouts and their associated data</li> <li>Must have experiment data access permissions</li> <li>Holdouts feature must be enabled for this project</li> </ul> Common causes: <ul> <li>Insufficient user permissions for holdout data access</li> <li>Project-level permissions don't include experiment data viewing</li> <li>Organization-level policies restrict holdout information access</li> <li>Holdouts feature flag is disabled for this project</li> </ul>

404Not Found - The specified holdout does not exist or you don't have access to it. 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 permanently deleted</li> <li>Insufficient permissions to view this holdout or its experiments</li> </ul> Note: Returns 404 even if holdout exists but you lack permissions, for security reasons.

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