Fetch a list of holdouts for a specific rule_key
", "contentType": "application/json", "request": { "pathParameters": [ { "kind": "required", "name": "project_id", "type": "integer", "example": 12345, "description": "The project identifier" }, { "kind": "required", "name": "environment_key", "type": "string", "example": "production", "description": "The Environment identifier" }, { "kind": "required", "name": "rule_key", "type": "string", "example": "rule_key", "description": "The Rule identifier" } ], "headerParameters": [], "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": "Successful retrieval of a list of holdouts.
\nThe response includes RESTful JSON (https://restfuljson.org/) styled links. If a\nlink is not present in the response, it indicates a user is not authorized to access\nthe related resource.
", "jsonExample": "", "isExpanded": true, "schema": [ { "kind": "optional", "type": "array", "example": "[{\"environment_key\":\"production\",\"holdout_results_api_token\":\"SampleToken.eyJhbGciOiJIUzI1NiIsInR5cCI6IkpXVCJ9\",\"id\":12345,\"key\":\"growth_experiment_holdout\",\"name\":\"Q4 Growth Experiment Control\",\"status\":\"running\"},{\"environment_key\":\"production\",\"holdout_results_api_token\":\"SampleToken.eyJhbGciOiJIUzI1NiIsInR5cCI6IkpXVCJ9\",\"id\":12346,\"key\":\"checkout_flow_holdout\",\"name\":\"Checkout Flow Holdout Group\",\"status\":\"draft\"}]", "description": "A simple array of holdout objects without pagination metadata.
\nUsed by endpoints that return a basic list of holdouts, such as when fetching\nholdouts associated with a specific rule. This is the non-paginated variant.
", "customType": "HoldoutsList", "schema": [ { "name": "archived", "kind": "optional", "type": "boolean", "description": "Whether the holdout is archived. Archived holdouts are hidden from normal views\nbut retain their historical data and configuration.\n", "example": false }, { "name": "audience_conditions", "kind": "optional", "type": "array", "description": "Defines which audiences this holdout applies to. If omitted, the holdout applies to all users.\nUses logical operators like 'and', 'or', 'not' to combine multiple audience conditions.
", "example": "[\"[\"or\",{\"audience_id\":5340810295},{\"audience_id\":1234567890}]\"]", "itemType": "object", "customType": "object[]", "itemExample": "[\"or\",{\"audience_id\":5340810295},{\"audience_id\":1234567890}]", "itemDefault": "" }, { "name": "audience_ids", "kind": "optional", "type": "array", "deprecated": true, "description": "Warning: Deprecated\nDEPRECATED: Use audience_conditions instead. List of audience IDs that this holdout applies to.\nThis field is maintained for backward compatibility.
", "example": "[5340810295,1234567890]", "itemType": "integer", "customType": "integer[]", "itemExample": "", "itemDefault": "" }, { "name": "created_by_user_email", "kind": "optional", "type": "string", "readOnly": true, "description": "Email address of the user who created the holdout.", "example": "user@company.com" }, { "name": "created_time", "kind": "optional", "type": "stringThe environment where this holdout is active (e.g., 'production', 'staging').\nThe holdout only affects traffic in this specific environment.
", "example": "production" }, { "name": "environment_name", "kind": "optional", "type": "string", "readOnly": true, "description": "The human-readable name of the environment where this holdout is active.
", "example": "Production" }, { "name": "exclude_targeted_deliveries", "kind": "optional", "type": "boolean", "description": "When true, Targeted Delivery rules are excluded from this holdout, so\nholdout users are not withheld from them. Targeted Deliveries represent\npermanent ship decisions rather than active experiments, so there is\nnothing to measure by withholding them.\nApplies to global holdouts only; ignored for local holdouts.\nCan only be changed while the holdout is in draft status.\nDefaults to false.
", "example": false, "default": false }, { "name": "holdout_results_api_token", "kind": "optional", "type": "string", "readOnly": true, "description": "API token for accessing holdout results and analytics data.\nThis token is dynamically generated for each API response and provides\nsecure access to holdout-specific results endpoints.
", "example": "SampleToken.eyJhbGciOiJIUzI1NiIsInR5cCI6IkpXVCJ9" }, { "name": "id", "kind": "required", "type": "integer", "readOnly": true, "description": "System-generated unique identifier for the holdout.
", "example": 12345 }, { "name": "key", "kind": "required", "type": "string", "description": "Unique user-defined identifier for the holdout within the project.\nMust contain only alphanumeric characters, underscores, and hyphens.
", "example": "annual_growth_holdout", "maxLength": 64, "pattern": "^[a-zA-Z0-9_\\-]+$" }, { "name": "metrics", "kind": "optional", "type": "array", "description": "List of metrics being tracked and analyzed for this holdout.\nThese metrics help measure the impact of experiments on the control group.\n", "modelRef": "#/components/schemas/Metric", "customType": "Metric[]", "schema": [ { "name": "aggregator", "kind": "required", "type": "stringThe aggregation function for the numerator of the metric. 'unique' measures the number of unique visitors/sessions that include the specified Event. 'count' measures the total number of occurrences of Event for the scope (visitor/session). 'sum' is the sum of the 'field' value
", "enum": [ "unique", "count", "sum", "ratio" ] }, { "name": "display_title", "kind": "optional", "type": "string", "description": "An optional title for the unique metric configuration. If not provided, the event name will be used.
" }, { "name": "display_unit", "kind": "optional", "type": "string", "description": "An optional name for the unit of the unique metric configuration." }, { "name": "event_id", "kind": "optional", "type": "integerThe ID for the Event to select data from. Omitted for global metrics that are not relative to a specific Event, i.e. \"overall revenue\"
", "example": 32334454244, "format": "int64" }, { "name": "event_properties", "kind": "optional", "type": "object", "description": "", "example": "", "schema": [ { "name": "filter", "kind": "optional", "type": "object", "description": "", "example": "", "schema": [ { "name": "combine_operator", "kind": "optional", "type": "stringThe field to aggregate for the numerator of the metric. Required when 'aggregator' = 'sum', otherwise omitted
", "enum": [ "revenue", "value" ] }, { "name": "id", "kind": "optional", "type": "string", "description": "A unique identifier for the metric configuration." }, { "name": "metrics", "kind": "optional", "type": "array", "description": "", "modelRef": "#/components/schemas/SubMetric", "customType": "SubMetric[]", "schema": [ { "name": "aggregator", "kind": "optional", "type": "string", "description": "" }, { "name": "display_title", "kind": "optional", "type": "string", "nullable": true, "description": "" }, { "name": "event_id", "kind": "optional", "type": "integer", "description": "" }, { "name": "event_type", "kind": "optional", "type": "string", "description": "" }, { "name": "field", "kind": "optional", "type": "string", "nullable": true, "description": "" }, { "name": "role", "kind": "optional", "type": "stringSpecifies how Events should be grouped together. Can also be thought of as the denonimator of the metric. 'session' divides by the number of sessions. \"Influenced sessions\", or sessions that do not contain a decision Event but carry a decision from a previous session are not included in counts for numerator or denominator. 'visitor' divides by the number of visitors. 'event' divides by the total occurrences (impressions) of the specified Event
", "enum": [ "session", "visitor", "event" ] }, { "name": "visibility", "kind": "optional", "type": "stringHuman-readable name for the holdout displayed in the UI.
", "example": "Annual Growth Control Group", "maxLength": 255 }, { "name": "project_id", "kind": "optional", "type": "integerProject objects returned by cross-project GET endpoints.\nFor global-scope holdouts, lists target project IDs.\nEmpty array for local-scope holdouts.\nFrontend resolves project names via entity-management API.
", "example": "[{\"id\":123}]", "itemType": "object", "customType": "object[]", "schema": [ { "name": "id", "kind": "optional", "type": "integerEnriched rule objects returned by cross-project GET endpoints.\nFor local-scope holdouts, lists target rules with metadata.\nEmpty array for global-scope holdouts.
", "example": "[{\"flag_key\":\"my_flag\",\"id\":456,\"key\":\"experiment_rule_a\",\"name\":\"Experiment Rule A\",\"project_id\":123}]", "itemType": "object", "customType": "object[]", "schema": [ { "name": "flag_id", "kind": "optional", "type": "integerDefines the scope of the holdout:
\nCurrent operational status of the holdout:
\nPercentage of traffic allocated to this holdout, expressed in basis points (1/100th of a percent).\nFor example: 100 = 1%, 1000 = 10%, 5000 = 50%. The remaining traffic sees experiments normally.
", "example": 1000, "minimum": 0, "maximum": 10000 }, { "name": "updated_time", "kind": "optional", "type": "stringRESTful link to fetch this holdout's details.\nFor project-scoped endpoints: /projects/{project_id}/holdouts/{holdout_id}\nFor cross-project endpoints: /holdouts/{holdout_id}
", "example": "/holdouts/12345" }, { "name": "urn", "kind": "optional", "type": "string", "readOnly": true, "description": "Universal Resource Name (URN) for the holdout, used for global identification.
", "example": "holdout.flag.optimizely.com::12345" } ], "modelRef": "#/components/schemas/HoldoutsList", "isExpanded": true } ] }, { "statusCode": "400", "description": "Malformed requests and invalid parameter names and types", "jsonExample": "", "isExpanded": true }, { "statusCode": "401", "description": "Invalid credentials", "jsonExample": "", "isExpanded": true }, { "statusCode": "403", "description": "Do not have permission to perform the operation", "jsonExample": "", "isExpanded": true }, { "statusCode": "404", "description": "Not found. No content", "jsonExample": "", "isExpanded": true } ], "hasXCodeSamples": false, "examples": { "languages": [ { "id": "AxV89eq0zYO0gn2JTPr7_", "language": "curl", "label": "cURL", "code": "curl --request GET \\\n --url https://api.optimizely.com/flags/v1//projects/{project_id}/environments/{environment_key}/rule/{rule_key}/holdouts \\\n --header 'accept: application/json'" }, { "id": "hMUXyJmed5MOjylGWVQ27", "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}/environments/{environment_key}/rule/{rule_key}/holdouts\", requestOptions)\n .then(response => response.text())\n .then(result => console.log(result))\n .catch(error => console.log('error', error));" }, { "id": "C3MojSI8utjw0niVz8dXb", "language": "ruby", "label": "Ruby", "code": "require \"uri\"\nrequire \"json\"\nrequire \"net/http\"\n\nurl = URI(\"https://api.optimizely.com/flags/v1//projects/{project_id}/environments/{environment_key}/rule/{rule_key}/holdouts\")\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": "rzLHa91408rbKeMQ1RCnv", "language": "python", "label": "Python", "code": "import requests\nimport json\n\nurl = \"https://api.optimizely.com/flags/v1//projects/{project_id}/environments/{environment_key}/rule/{rule_key}/holdouts\"\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": "AxV89eq0zYO0gn2JTPr7_" }, "results": { "languages": [ { "id": "response-0-200", "language": "200", "code": "// Successful retrieval of a list of holdouts.\nThe response includes RESTful JSON (https://restfuljson.org/) styled links. If a\nlink is not present in the response, it indicates a user is not authorized to access\nthe related resource.\n[\n {\n \"archived\": false,\n \"audience_conditions\": [\n {}\n ],\n \"audience_ids\": [\n 0\n ],\n \"created_by_user_email\": \"user@company.com\",\n \"created_time\": \"2023-12-15T10:00:00.000Z\",\n \"description\": \"Holdout group to measure the overall impact of our growth experiments throughout the year\",\n \"end_time\": \"2024-12-31T23:59:59.000Z\",\n \"environment_key\": \"production\",\n \"environment_name\": \"Production\",\n \"exclude_targeted_deliveries\": false,\n \"holdout_results_api_token\": \"SampleToken.eyJhbGciOiJIUzI1NiIsInR5cCI6IkpXVCJ9\",\n \"id\": 12345,\n \"key\": \"annual_growth_holdout\",\n \"metrics\": [\n {\n \"aggregator\": \"\",\n \"display_title\": \"\",\n \"display_unit\": \"\",\n \"event_id\": 32334454244,\n \"event_properties\": {\n \"filter\": {\n \"combine_operator\": \"\",\n \"conditions\": [\n {\n \"name\": \"\",\n \"operator\": \"\",\n \"type\": \"\",\n \"value\": \"\"\n }\n ]\n }\n },\n \"event_type\": \"\",\n \"field\": \"\",\n \"id\": \"\",\n \"metrics\": [\n {\n \"aggregator\": \"\",\n \"display_title\": \"\",\n \"event_id\": 0,\n \"event_type\": \"\",\n \"field\": \"\",\n \"role\": \"\",\n \"scope\": \"\"\n }\n ],\n \"project_id\": 0,\n \"scope\": \"\",\n \"visibility\": \"\",\n \"winning_direction\": \"\"\n }\n ],\n \"name\": \"Annual Growth Control Group\",\n \"project_id\": 98765,\n \"projects\": [\n {\n \"id\": \"\"\n }\n ],\n \"revision\": 3,\n \"rules\": [\n {\n \"flag_id\": \"\",\n \"flag_key\": \"\",\n \"flag_name\": \"\",\n \"id\": \"\",\n \"key\": \"\",\n \"name\": \"\",\n \"project_id\": \"\"\n }\n ],\n \"scope\": \"global\",\n \"start_time\": \"2024-01-01T00:00:00.000Z\",\n \"status\": \"running\",\n \"traffic_allocation\": 1000,\n \"updated_time\": \"2024-01-01T10:00:00.000Z\",\n \"url\": \"/holdouts/12345\",\n \"urn\": \"holdout.flag.optimizely.com::12345\"\n }\n]" }, { "id": "response-1-400", "language": "400", "code": "// Malformed requests and invalid parameter names and types\n" }, { "id": "response-2-401", "language": "401", "code": "// Invalid credentials\n" }, { "id": "response-3-403", "language": "403", "code": "// Do not have permission to perform the operation\n" }, { "id": "response-4-404", "language": "404", "code": "// Not found. No content\n" } ], "selectedLanguageId": "response-0-200" } }, "children": [ { "text": "" } ] }