Retrieves a list of experiments that are connected to a specific holdout through the system's data relationships.
\nWhat you'll get:
\nHow experiments connect to holdouts:\nThis endpoint traverses complex database relationships to find experiments associated with a holdout:
\nData relationships explained:
\nUse cases:
\nPerformance considerations:
\nThis endpoint provides crucial visibility into the complex relationships between holdouts and the experiments they may influence.
", "contentType": "application/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": "Successfully retrieved the list of experiments associated with the holdout.
\nResponse structure:
\nData interpretation:
\nEmpty response scenarios:
\nUse this data for:
\nA collection of experiment rules associated with a holdout.
\nEach item represents an experiment that is connected to the holdout through database\nrelationships between holdouts, flags, rulesets, rules, and reports. The list contains\nexperiment timing information and deployed variation details.
", "customType": "HoldoutExperiments", "schema": [ { "name": "deployed_variation_id", "kind": "optional", "type": "integerThe unique identifier of the deployed variation for this experiment.\nThis is the Variation.id that matches the Rule.deployed_variation_key.\nMay be null if no deployed variation is configured.
", "example": 9876543210, "format": "int64" }, { "name": "deployed_variation_key", "kind": "optional", "type": "string", "nullable": true, "description": "The key of the deployed variation for this experiment.\nThis is the Variation.key that corresponds to the deployed_variation_id.\nMay be null if no deployed variation is configured or if the variation doesn't exist.
", "example": "control" }, { "name": "deployed_variation_name", "kind": "optional", "type": "string", "nullable": true, "description": "The human-readable name of the deployed variation for this experiment.\nThis is the Variation.name that corresponds to the deployed_variation_id.\nMay be null if no deployed variation is configured or if the variation doesn't exist.
", "example": "Control Variation" }, { "name": "experiment_end_time", "kind": "optional", "type": "stringThe end time of the experiment report. This timestamp indicates when the\nexperiment finished collecting data. May be null for ongoing experiments.\nSourced from Report.end_time.
", "example": "2024-03-15T23:59:59.000Z", "format": "date-time" }, { "name": "experiment_id", "kind": "required", "type": "integerThe layer experiment ID from the rule associated with this holdout.\nThis corresponds to the Rule.layer_experiment_id field in the database.
", "example": 1234567890, "format": "int64" }, { "name": "experiment_start_time", "kind": "optional", "type": "stringThe start time of the experiment report. This timestamp indicates when the\nexperiment began collecting data. Sourced from Report.start_time.
", "example": "2024-01-15T10:00:00.000Z", "format": "date-time" } ], "modelRef": "#/components/schemas/HoldoutExperiments", "isExpanded": true } ] }, { "statusCode": "400", "description": "Bad Request - Invalid request parameters or malformed IDs.
\nCommon causes:
\nholdout_id format (must be a positive integer)project_id format (must be a positive integer)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": "Forbidden - You don't have permission to view holdout experiments in this project.
\nPermission requirements:
\nCommon causes:
\nhttps://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": "404", "description": "Not Found - The specified holdout does not exist or you don't have access to it.
\nPossible reasons:
\nNote: Returns 404 even if holdout exists but you lack permissions, for security reasons.
", "jsonExample": "", "isExpanded": true, "subExamples": [ { "label": "GENERATED", "code": "// Not Found - The specified holdout does not exist or you don't have access to it.\nPossible reasons:\n\nHoldout ID does not exist in the specified project\nProject ID does not exist or you don't have access to it\nHoldout was permanently deleted\nInsufficient permissions to view this holdout or its experiments\n\nNote: Returns 404 even if holdout exists but you lack permissions, for security reasons.\n{\n \"detail\": \"\",\n \"status\": 0,\n \"title\": \"\",\n \"type\": \"\",\n \"uuid\": \"\"\n}" }, { "label": "holdout_not_found", "code": "// Holdout does not exist\n{\n \"detail\": \"Holdout not found with id '987'\",\n \"status\": 404,\n \"title\": \"Holdout not found\",\n \"type\": \"about:blank\"\n}" }, { "label": "project_not_found", "code": "// Project does not exist\n{\n \"detail\": \"Project not found with id '12345'\",\n \"status\": 404,\n \"title\": \"Project not found\",\n \"type\": \"about:blank\"\n}" } ], "schema": [ { "kind": "optional", "type": "object", "example": "{\"detail\":\"Holdout not found with id '987'\",\"status\":404,\"title\":\"Holdout not found\",\"type\":\"about:blank\"}", "examples": [ { "label": "Holdout does not exist", "value": "{\"detail\":\"Holdout not found with id '987'\",\"status\":404,\"title\":\"Holdout not found\",\"type\":\"about:blank\"}" }, { "label": "Project does not exist", "value": "{\"detail\":\"Project not found with id '12345'\",\"status\":404,\"title\":\"Project not found\",\"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 } ] } ], "hasXCodeSamples": false, "examples": { "languages": [ { "id": "sJ_j8S5IQjHNHQYi4hLO7", "language": "curl", "label": "cURL", "code": "curl --request GET \\\n --url https://api.optimizely.com/flags/v1//projects/{project_id}/holdouts/{holdout_id}/experiments \\\n --header 'accept: application/json'" }, { "id": "MEVl9OeAtcvf6UdT_yZBN", "language": "javascript", "label": "javascript", "code": "var myHeaders = new Headers();\nmyHeaders.append(\"accept\", \"application/json\");\nmyHeaders.append(\"content-type\", \"application/json\");\n\nvar requestOptions = {\n method: 'GET',\n headers: myHeaders,\n redirect: 'follow'\n};\n\nfetch(\"https://api.optimizely.com/flags/v1//projects/{project_id}/holdouts/{holdout_id}/experiments\", requestOptions)\n .then(response => response.text())\n .then(result => console.log(result))\n .catch(error => console.log('error', error));" }, { "id": "5hZiMaXCFCQuGlMcpQMpm", "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}/experiments\")\n\nhttps = Net::HTTP.new(url.host, url.port)\nhttps.use_ssl = true\n\nrequest = Net::HTTP::Get.new(url)\nrequest[\"accept\"] = \"application/json\"\nrequest[\"content-type\"] = \"application/json\"\n\nresponse = https.request(request)\nputs response.read_body\n" }, { "id": "g1b6ztxAJ9M4bO8xy7ZUc", "language": "python", "label": "Python", "code": "import requests\nimport json\n\nurl = \"https://api.optimizely.com/flags/v1//projects/{project_id}/holdouts/{holdout_id}/experiments\"\n\npayload = {}\nheaders = {\n 'accept': 'application/json',\n 'content-type': 'application/json'\n}\n\nresponse = requests.request(\"GET\", url, headers=headers, data=payload)\n\nprint(response.text)\n" } ], "selectedLanguageId": "sJ_j8S5IQjHNHQYi4hLO7" }, "results": { "languages": [ { "id": "response-0-200", "language": "200", "code": "// Successfully retrieved the list of experiments associated with the holdout.\nResponse structure:\n\nReturns an array of experiment objects\nEach experiment contains identification, timing, and variation data\nEmpty or null values are automatically filtered out\nResults are ordered by the database query (typically by experiment_id)\n\nData interpretation:\n\nexperiment_id: References the layer_experiment_id from rules connected to this holdout\nTiming fields: Reflect actual experiment run periods from reports\ndeployed_variation_id: Present only when experiments have specific variation deployments\nMissing end_time: Indicates ongoing or perpetually running experiments\nMissing deployed_variation_id: Experiments without specific variation targeting\n\nEmpty response scenarios:\n\nHoldout exists but has no connected experiments (valid scenario)\nNo rules in the project match the holdout's configuration\nAll connected experiments have been archived or removed\n\nUse this data for:\n\nUnderstanding experiment overlap with holdout traffic\nPlanning holdout changes with awareness of affected experiments\nBuilding experiment impact reports and analytics\nCoordinating experiment timelines and traffic allocation\n[\n {\n \"deployed_variation_id\": 9876543210,\n \"deployed_variation_key\": \"control\",\n \"deployed_variation_name\": \"Control Variation\",\n \"experiment_end_time\": \"2024-03-15T23:59:59.000Z\",\n \"experiment_id\": 1234567890,\n \"experiment_start_time\": \"2024-01-15T10:00:00.000Z\"\n }\n]", "subExamples": [ { "label": "GENERATED", "code": "// Successfully retrieved the list of experiments associated with the holdout.\nResponse structure:\n\nReturns an array of experiment objects\nEach experiment contains identification, timing, and variation data\nEmpty or null values are automatically filtered out\nResults are ordered by the database query (typically by experiment_id)\n\nData interpretation:\n\nexperiment_id: References the layer_experiment_id from rules connected to this holdout\nTiming fields: Reflect actual experiment run periods from reports\ndeployed_variation_id: Present only when experiments have specific variation deployments\nMissing end_time: Indicates ongoing or perpetually running experiments\nMissing deployed_variation_id: Experiments without specific variation targeting\n\nEmpty response scenarios:\n\nHoldout exists but has no connected experiments (valid scenario)\nNo rules in the project match the holdout's configuration\nAll connected experiments have been archived or removed\n\nUse this data for:\n\nUnderstanding experiment overlap with holdout traffic\nPlanning holdout changes with awareness of affected experiments\nBuilding experiment impact reports and analytics\nCoordinating experiment timelines and traffic allocation\n[\n {\n \"deployed_variation_id\": 9876543210,\n \"deployed_variation_key\": \"control\",\n \"deployed_variation_name\": \"Control Variation\",\n \"experiment_end_time\": \"2024-03-15T23:59:59.000Z\",\n \"experiment_id\": 1234567890,\n \"experiment_start_time\": \"2024-01-15T10:00:00.000Z\"\n }\n]" }, { "label": "concluded_experiments", "code": "// Historical experiments with complete data\n[\n {\n \"deployed_variation_id\": 6666666666,\n \"experiment_end_time\": \"2024-07-31T23:59:59.000Z\",\n \"experiment_id\": 5555555555,\n \"experiment_start_time\": \"2024-07-01T10:00:00.000Z\"\n },\n {\n \"deployed_variation_id\": 8888888888,\n \"experiment_end_time\": \"2024-06-30T23:59:59.000Z\",\n \"experiment_id\": 7777777777,\n \"experiment_start_time\": \"2024-06-15T14:00:00.000Z\"\n }\n]" }, { "label": "multiple_experiments", "code": "// Holdout with multiple connected experiments\n[\n {\n \"deployed_variation_id\": 9876543210,\n \"deployed_variation_key\": \"control\",\n \"deployed_variation_name\": \"Control Variation\",\n \"experiment_end_time\": \"2024-09-30T23:59:59.000Z\",\n \"experiment_id\": 1234567890,\n \"experiment_start_time\": \"2024-09-01T10:00:00.000Z\"\n },\n {\n \"deployed_variation_id\": 8765432109,\n \"deployed_variation_key\": \"treatment\",\n \"deployed_variation_name\": \"Treatment Variation\",\n \"experiment_end_time\": null,\n \"experiment_id\": 2345678901,\n \"experiment_start_time\": \"2024-09-15T14:30:00.000Z\"\n },\n {\n \"deployed_variation_id\": null,\n \"experiment_end_time\": \"2024-08-31T23:59:59.000Z\",\n \"experiment_id\": 3456789012,\n \"experiment_start_time\": \"2024-08-01T09:00:00.000Z\"\n }\n]" }, { "label": "no_experiments", "code": "// Holdout with no connected experiments\n[]" }, { "label": "ongoing_experiments", "code": "// Active experiments without end times\n[\n {\n \"deployed_variation_id\": 2222222222,\n \"deployed_variation_key\": \"variation_a\",\n \"deployed_variation_name\": \"Variation A\",\n \"experiment_end_time\": null,\n \"experiment_id\": 1111111111,\n \"experiment_start_time\": \"2024-09-10T12:00:00.000Z\"\n },\n {\n \"deployed_variation_id\": null,\n \"experiment_end_time\": null,\n \"experiment_id\": 3333333333,\n \"experiment_start_time\": \"2024-09-16T08:00:00.000Z\"\n }\n]" } ] }, { "id": "response-1-400", "language": "400", "code": "// Bad Request - Invalid request parameters or malformed IDs.\nCommon causes:\n\nInvalid holdout_id format (must be a positive integer)\nInvalid project_id format (must be a positive integer)\nMalformed request structure or unsupported query parameters\n{\n \"detail\": \"\",\n \"status\": 0,\n \"title\": \"\",\n \"type\": \"\",\n \"uuid\": \"\"\n}" }, { "id": "response-2-401", "language": "401", "code": "// Invalid credentials\n" }, { "id": "response-3-403", "language": "403", "code": "// Forbidden - You don't have permission to view holdout experiments in this project.\nPermission requirements:\n\nMust have project-level read access\nMust have permissions to view holdouts and their associated data\nMust have experiment data access permissions\nHoldouts feature must be enabled for this project\n\nCommon causes:\n\nInsufficient user permissions for holdout data access\nProject-level permissions don't include experiment data viewing\nOrganization-level policies restrict holdout information access\nHoldouts feature flag is disabled for this project\n{\n \"detail\": \"\",\n \"status\": 0,\n \"title\": \"\",\n \"type\": \"\",\n \"uuid\": \"\"\n}", "subExamples": [ { "label": "GENERATED", "code": "// Forbidden - You don't have permission to view holdout experiments in this project.\nPermission requirements:\n\nMust have project-level read access\nMust have permissions to view holdouts and their associated data\nMust have experiment data access permissions\nHoldouts feature must be enabled for this project\n\nCommon causes:\n\nInsufficient user permissions for holdout data access\nProject-level permissions don't include experiment data viewing\nOrganization-level policies restrict holdout information access\nHoldouts feature flag is disabled for this project\n{\n \"detail\": \"\",\n \"status\": 0,\n \"title\": \"\",\n \"type\": \"\",\n \"uuid\": \"\"\n}" }, { "label": "feature_disabled", "code": "// Holdouts feature disabled\n{\n \"detail\": \"Holdouts feature is not enabled for this project\",\n \"status\": 403,\n \"title\": \"Feature not enabled\",\n \"type\": \"about:blank\"\n}" }, { "label": "insufficient_permissions", "code": "// Insufficient permissions\n{\n \"detail\": \"Permission denied - insufficient privileges to view holdout experiments\",\n \"status\": 403,\n \"title\": \"Forbidden\",\n \"type\": \"about:blank\"\n}" } ] }, { "id": "response-4-404", "language": "404", "code": "// Not Found - The specified holdout does not exist or you don't have access to it.\nPossible reasons:\n\nHoldout ID does not exist in the specified project\nProject ID does not exist or you don't have access to it\nHoldout was permanently deleted\nInsufficient permissions to view this holdout or its experiments\n\nNote: Returns 404 even if holdout exists but you lack permissions, for security reasons.\n{\n \"detail\": \"\",\n \"status\": 0,\n \"title\": \"\",\n \"type\": \"\",\n \"uuid\": \"\"\n}", "subExamples": [ { "label": "GENERATED", "code": "// Not Found - The specified holdout does not exist or you don't have access to it.\nPossible reasons:\n\nHoldout ID does not exist in the specified project\nProject ID does not exist or you don't have access to it\nHoldout was permanently deleted\nInsufficient permissions to view this holdout or its experiments\n\nNote: Returns 404 even if holdout exists but you lack permissions, for security reasons.\n{\n \"detail\": \"\",\n \"status\": 0,\n \"title\": \"\",\n \"type\": \"\",\n \"uuid\": \"\"\n}" }, { "label": "holdout_not_found", "code": "// Holdout does not exist\n{\n \"detail\": \"Holdout not found with id '987'\",\n \"status\": 404,\n \"title\": \"Holdout not found\",\n \"type\": \"about:blank\"\n}" }, { "label": "project_not_found", "code": "// Project does not exist\n{\n \"detail\": \"Project not found with id '12345'\",\n \"status\": 404,\n \"title\": \"Project not found\",\n \"type\": \"about:blank\"\n}" } ] } ], "selectedLanguageId": "response-0-200" } }, "children": [ { "text": "" } ] }