Fetches a single holdout by ID without requiring a project_id in the URL.\nThe response is filtered to only include projects and rules the user has\nFLAGS_READ permission on.
\nResponse includes standard Holdout schema plus additional fields that vary by scope:
\nGlobal scope:
\nprojects: array of objects, each containing id (integer) — filtered to permitted projectsrules: empty array []Local scope:
\nprojects: empty array []rules: array of enriched rule objects, each containing:\nid (integer)name (string)key (string)flag_id (integer)flag_name (string)flag_key (string)project_id (integer)The frontend fetches project names separately as needed.
\nGated behind the holdouts-m2 feature flag.
Successful retrieval, creation or update of a Holdout.
\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": "object", "example": "{\"archived\":false,\"audience_conditions\":[\"or\",{\"audience_id\":5340810295}],\"created_by_user_email\":\"user@company.com\",\"created_time\":\"2023-12-15T10:00:00.000Z\",\"description\":\"Holdout group to measure the overall impact of our growth experiments throughout the year\",\"environment_key\":\"production\",\"holdout_results_api_token\":\"SampleToken.eyJhbGciOiJIUzI1NiIsInR5cCI6IkpXVCJ9\",\"id\":12345,\"key\":\"annual_growth_holdout\",\"metrics\":[{\"aggregator\":\"unique\",\"display_title\":\"Conversion Rate\",\"scope\":\"visitor\",\"winning_direction\":\"increasing\"}],\"name\":\"Annual Growth Control Group\",\"project_id\":98765,\"revision\":3,\"scope\":\"global\",\"start_time\":\"2024-01-01T00:00:00.000Z\",\"status\":\"running\",\"traffic_allocation\":1000,\"updated_time\":\"2024-01-01T10:00:00.000Z\",\"urn\":\"holdout.flag.optimizely.com::12345\"}", "description": "Represents a holdout experiment that reserves a portion of traffic to measure the impact of feature flags and experiments.
\nHoldouts help establish control groups by excluding a percentage of users from seeing any experiments, allowing you to measure the overall impact of your experimentation program against a baseline.
", "customType": "Holdout", "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/Holdout", "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": "QOU4KDOBN_v6qQZwTryrW", "language": "curl", "label": "cURL", "code": "curl --request GET \\\n --url https://api.optimizely.com/flags/v1//holdouts/{holdout_id} \\\n --header 'accept: application/json'" }, { "id": "jWqusNx2r_yR3TQKL_heo", "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//holdouts/{holdout_id}\", requestOptions)\n .then(response => response.text())\n .then(result => console.log(result))\n .catch(error => console.log('error', error));" }, { "id": "ihVtm4FD9E-v85jN9isRF", "language": "ruby", "label": "Ruby", "code": "require \"uri\"\nrequire \"json\"\nrequire \"net/http\"\n\nurl = URI(\"https://api.optimizely.com/flags/v1//holdouts/{holdout_id}\")\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": "fTwYyrWmWZp_Q_y5WOOg0", "language": "python", "label": "Python", "code": "import requests\nimport json\n\nurl = \"https://api.optimizely.com/flags/v1//holdouts/{holdout_id}\"\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": "QOU4KDOBN_v6qQZwTryrW" }, "results": { "languages": [ { "id": "mTb0SLbxpSWENafo1sJ8R", "language": "200", "code": "// Successful retrieval, creation or update of a Holdout.\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 \"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}" }, { "id": "Pk5ew8-I0A5pVrSn3QU4x", "language": "401", "code": "// Invalid credentials\n" }, { "id": "__YM8mY8mv0C6A52D01BV", "language": "403", "code": "// Do not have permission to perform the operation\n" }, { "id": "LRA0pDlKxlbkVO4i__aOK", "language": "404", "code": "// Not found. No content\n" } ], "selectedLanguageId": "mTb0SLbxpSWENafo1sJ8R" } }, "children": [ { "text": "" } ] }