Create holdout

POST

/api/v2/projects/:projectKey/environments/:environmentKey/holdouts

POST

/api/v2/projects/:projectKey/environments/:environmentKey/holdouts

1 import requests
2 
3 url = "https://app.launchdarkly.com/api/v2/projects/projectKey/environments/environmentKey/holdouts"
4 
5 payload = {}
6 headers = {
7     "Authorization": "<apiKey>",
8     "Content-Type": "application/json"
9 }
10 
11 response = requests.post(url, json=payload, headers=headers)
12 
13 print(response.json())

Try it

201Created

1 {
2   "_id": "_id",
3   "status": "created",
4   "holdoutAmount": "holdoutAmount",
5   "createdAt": 1000000,
6   "updatedAt": 1000000,
7   "baseExperiment": {
8     "key": "experiment-key-123abc",
9     "name": "Example experiment",
10     "_maintainerId": "12ab3c45de678910fgh12345",
11     "_creationDate": 1000000,
12     "environmentKey": "environmentKey",
13     "_links": {
14       "parent": {
15         "href": "/api/v2/projects/my-project/environments/my-environment",
16         "type": "application/json"
17       },
18       "self": {
19         "href": "/api/v2/projects/my-project/environments/my-environment/experiments/my-experiment",
20         "type": "application/json"
21       }
22     },
23     "_id": "12ab3c45de678910fgh12345",
24     "description": "An example experiment, used in testing",
25     "archivedDate": 1000000,
26     "holdoutId": "f3b74309-d581-44e1-8a2b-bb2933b4fe40",
27     "currentIteration": {
28       "hypothesis": "The new button placement will increase conversion",
29       "status": "running",
30       "createdAt": 1000000,
31       "_id": "12ab3c45de678910fgh12345",
32       "startedAt": 1000000,
33       "endedAt": 1000000,
34       "winningTreatmentId": "122c9f3e-da26-4321-ba68-e0fc02eced58",
35       "winningReason": "We ran this iteration for two weeks and the winning variation was clear",
36       "canReshuffleTraffic": true,
37       "flags": {
38         "key": {
39           "_links": {
40             "self": {
41               "href": "/api/v2/flags/my-project/my-flag",
42               "type": "application/json"
43             }
44           },
45           "targetingRule": "fallthrough",
46           "targetingRuleDescription": "Customers who live in Canada",
47           "flagConfigVersion": 12,
48           "notInExperimentVariationId": "e432f62b-55f6-49dd-a02f-eb24acf39d05"
49         }
50       },
51       "primaryMetric": {
52         "key": "metric-key-123abc",
53         "_versionId": "_versionId",
54         "name": "My metric",
55         "kind": "pageview",
56         "_links": {
57           "self": {
58             "href": "/api/v2/metrics/my-project/my-metric",
59             "type": "application/json"
60           }
61         },
62         "isGroup": true,
63         "isNumeric": true,
64         "metrics": [
65           {
66             "key": "metric-key-123abc",
67             "name": "Example metric",
68             "kind": "pageview",
69             "_links": {
70               "self": {
71                 "href": "/api/v2/metrics/my-project/my-metric",
72                 "type": "application/json"
73               }
74             },
75             "_versionId": "version-id-123abc",
76             "isNumeric": true,
77             "nameInGroup": "Step 1"
78           }
79         ]
80       },
81       "primarySingleMetric": {
82         "key": "metric-key-123abc",
83         "name": "Example metric",
84         "kind": "pageview",
85         "_links": {
86           "self": {
87             "href": "/api/v2/metrics/my-project/my-metric",
88             "type": "application/json"
89           }
90         },
91         "_versionId": "version-id-123abc",
92         "isNumeric": true
93       },
94       "primaryFunnel": {
95         "key": "metric-group-key-123abc",
96         "name": "My metric group",
97         "kind": "funnel",
98         "_links": {
99           "parent": {
100             "href": "/api/v2/projects/my-project",
101             "type": "application/json"
102           },
103           "self": {
104             "href": "/api/v2/projects/my-project/metric-groups/my-metric-group",
105             "type": "application/json"
106           }
107         },
108         "metrics": [
109           {
110             "key": "metric-key-123abc",
111             "name": "Example metric",
112             "kind": "pageview",
113             "_links": {
114               "self": {
115                 "href": "/api/v2/metrics/my-project/my-metric",
116                 "type": "application/json"
117               }
118             },
119             "_versionId": "version-id-123abc",
120             "isNumeric": true,
121             "nameInGroup": "Step 1"
122           }
123         ]
124       },
125       "randomizationUnit": "user",
126       "attributes": [
127         "attributes"
128       ],
129       "treatments": [
130         {
131           "name": "Treatment 1",
132           "allocationPercent": "10",
133           "_id": "122c9f3e-da26-4321-ba68-e0fc02eced58",
134           "baseline": true
135         }
136       ],
137       "metrics": [
138         {
139           "key": "metric-key-123abc",
140           "_versionId": "_versionId",
141           "name": "My metric",
142           "kind": "pageview",
143           "_links": {
144             "self": {
145               "href": "/api/v2/metrics/my-project/my-metric",
146               "type": "application/json"
147             }
148           },
149           "isGroup": true,
150           "isNumeric": true,
151           "metrics": [
152             {
153               "key": "metric-key-123abc",
154               "name": "Example metric",
155               "kind": "pageview",
156               "_links": {
157                 "self": {
158                   "href": "/api/v2/metrics/my-project/my-metric",
159                   "type": "application/json"
160                 }
161               },
162               "_versionId": "version-id-123abc",
163               "isNumeric": true,
164               "nameInGroup": "Step 1"
165             }
166           ]
167         }
168       ],
169       "layerSnapshot": {
170         "key": "checkout-flow",
171         "name": "Checkout Flow",
172         "reservationPercent": 10,
173         "otherReservationPercent": 70
174       },
175       "secondaryMetrics": [
176         {
177           "key": "metric-key-123abc",
178           "name": "Example metric",
179           "kind": "pageview",
180           "_links": {
181             "self": {
182               "href": "/api/v2/metrics/my-project/my-metric",
183               "type": "application/json"
184             }
185           },
186           "_versionId": "version-id-123abc",
187           "isNumeric": true
188         }
189       ]
190     },
191     "draftIteration": {
192       "hypothesis": "The new button placement will increase conversion",
193       "status": "running",
194       "createdAt": 1000000,
195       "_id": "12ab3c45de678910fgh12345",
196       "startedAt": 1000000,
197       "endedAt": 1000000,
198       "winningTreatmentId": "122c9f3e-da26-4321-ba68-e0fc02eced58",
199       "winningReason": "We ran this iteration for two weeks and the winning variation was clear",
200       "canReshuffleTraffic": true,
201       "flags": {
202         "key": {
203           "_links": {
204             "self": {
205               "href": "/api/v2/flags/my-project/my-flag",
206               "type": "application/json"
207             }
208           },
209           "targetingRule": "fallthrough",
210           "targetingRuleDescription": "Customers who live in Canada",
211           "flagConfigVersion": 12,
212           "notInExperimentVariationId": "e432f62b-55f6-49dd-a02f-eb24acf39d05"
213         }
214       },
215       "primaryMetric": {
216         "key": "metric-key-123abc",
217         "_versionId": "_versionId",
218         "name": "My metric",
219         "kind": "pageview",
220         "_links": {
221           "self": {
222             "href": "/api/v2/metrics/my-project/my-metric",
223             "type": "application/json"
224           }
225         },
226         "isGroup": true,
227         "isNumeric": true,
228         "metrics": [
229           {
230             "key": "metric-key-123abc",
231             "name": "Example metric",
232             "kind": "pageview",
233             "_links": {
234               "self": {
235                 "href": "/api/v2/metrics/my-project/my-metric",
236                 "type": "application/json"
237               }
238             },
239             "_versionId": "version-id-123abc",
240             "isNumeric": true,
241             "nameInGroup": "Step 1"
242           }
243         ]
244       },
245       "primarySingleMetric": {
246         "key": "metric-key-123abc",
247         "name": "Example metric",
248         "kind": "pageview",
249         "_links": {
250           "self": {
251             "href": "/api/v2/metrics/my-project/my-metric",
252             "type": "application/json"
253           }
254         },
255         "_versionId": "version-id-123abc",
256         "isNumeric": true
257       },
258       "primaryFunnel": {
259         "key": "metric-group-key-123abc",
260         "name": "My metric group",
261         "kind": "funnel",
262         "_links": {
263           "parent": {
264             "href": "/api/v2/projects/my-project",
265             "type": "application/json"
266           },
267           "self": {
268             "href": "/api/v2/projects/my-project/metric-groups/my-metric-group",
269             "type": "application/json"
270           }
271         },
272         "metrics": [
273           {
274             "key": "metric-key-123abc",
275             "name": "Example metric",
276             "kind": "pageview",
277             "_links": {
278               "self": {
279                 "href": "/api/v2/metrics/my-project/my-metric",
280                 "type": "application/json"
281               }
282             },
283             "_versionId": "version-id-123abc",
284             "isNumeric": true,
285             "nameInGroup": "Step 1"
286           }
287         ]
288       },
289       "randomizationUnit": "user",
290       "attributes": [
291         "attributes"
292       ],
293       "treatments": [
294         {
295           "name": "Treatment 1",
296           "allocationPercent": "10",
297           "_id": "122c9f3e-da26-4321-ba68-e0fc02eced58",
298           "baseline": true
299         }
300       ],
301       "metrics": [
302         {
303           "key": "metric-key-123abc",
304           "_versionId": "_versionId",
305           "name": "My metric",
306           "kind": "pageview",
307           "_links": {
308             "self": {
309               "href": "/api/v2/metrics/my-project/my-metric",
310               "type": "application/json"
311             }
312           },
313           "isGroup": true,
314           "isNumeric": true,
315           "metrics": [
316             {
317               "key": "metric-key-123abc",
318               "name": "Example metric",
319               "kind": "pageview",
320               "_links": {
321                 "self": {
322                   "href": "/api/v2/metrics/my-project/my-metric",
323                   "type": "application/json"
324                 }
325               },
326               "_versionId": "version-id-123abc",
327               "isNumeric": true,
328               "nameInGroup": "Step 1"
329             }
330           ]
331         }
332       ],
333       "layerSnapshot": {
334         "key": "checkout-flow",
335         "name": "Checkout Flow",
336         "reservationPercent": 10,
337         "otherReservationPercent": 70
338       },
339       "secondaryMetrics": [
340         {
341           "key": "metric-key-123abc",
342           "name": "Example metric",
343           "kind": "pageview",
344           "_links": {
345             "self": {
346               "href": "/api/v2/metrics/my-project/my-metric",
347               "type": "application/json"
348             }
349           },
350           "_versionId": "version-id-123abc",
351           "isNumeric": true
352         }
353       ]
354     },
355     "previousIterations": [
356       {
357         "hypothesis": "The new button placement will increase conversion",
358         "status": "running",
359         "createdAt": 1000000,
360         "_id": "12ab3c45de678910fgh12345",
361         "winningTreatmentId": "122c9f3e-da26-4321-ba68-e0fc02eced58",
362         "winningReason": "We ran this iteration for two weeks and the winning variation was clear",
363         "canReshuffleTraffic": true,
364         "primaryMetric": {
365           "key": "metric-key-123abc",
366           "_versionId": "_versionId",
367           "name": "My metric",
368           "kind": "pageview",
369           "_links": {
370             "self": {
371               "href": "/api/v2/metrics/my-project/my-metric",
372               "type": "application/json"
373             }
374           },
375           "isGroup": true,
376           "isNumeric": true,
377           "metrics": [
378             {
379               "key": "metric-key-123abc",
380               "name": "Example metric",
381               "kind": "pageview",
382               "_links": {
383                 "self": {
384                   "href": "/api/v2/metrics/my-project/my-metric",
385                   "type": "application/json"
386                 }
387               },
388               "_versionId": "version-id-123abc",
389               "isNumeric": true,
390               "nameInGroup": "Step 1"
391             }
392           ]
393         },
394         "primarySingleMetric": {
395           "key": "metric-key-123abc",
396           "name": "Example metric",
397           "kind": "pageview",
398           "_links": {
399             "self": {
400               "href": "/api/v2/metrics/my-project/my-metric",
401               "type": "application/json"
402             }
403           },
404           "_versionId": "version-id-123abc",
405           "isNumeric": true
406         },
407         "primaryFunnel": {
408           "key": "metric-group-key-123abc",
409           "name": "My metric group",
410           "kind": "funnel",
411           "_links": {
412             "parent": {
413               "href": "/api/v2/projects/my-project",
414               "type": "application/json"
415             },
416             "self": {
417               "href": "/api/v2/projects/my-project/metric-groups/my-metric-group",
418               "type": "application/json"
419             }
420           },
421           "metrics": [
422             {
423               "key": "metric-key-123abc",
424               "name": "Example metric",
425               "kind": "pageview",
426               "_links": {
427                 "self": {
428                   "href": "/api/v2/metrics/my-project/my-metric",
429                   "type": "application/json"
430                 }
431               },
432               "_versionId": "version-id-123abc",
433               "isNumeric": true,
434               "nameInGroup": "Step 1"
435             }
436           ]
437         },
438         "randomizationUnit": "user",
439         "treatments": [
440           {
441             "name": "Treatment 1",
442             "allocationPercent": "10",
443             "_id": "122c9f3e-da26-4321-ba68-e0fc02eced58",
444             "baseline": true
445           }
446         ],
447         "metrics": [
448           {
449             "key": "metric-key-123abc",
450             "_versionId": "_versionId",
451             "name": "My metric",
452             "kind": "pageview",
453             "_links": {
454               "self": {
455                 "href": "/api/v2/metrics/my-project/my-metric",
456                 "type": "application/json"
457               }
458             },
459             "isGroup": true,
460             "isNumeric": true,
461             "metrics": [
462               {
463                 "key": "metric-key-123abc",
464                 "name": "Example metric",
465                 "kind": "pageview",
466                 "_links": {
467                   "self": {
468                     "href": "/api/v2/metrics/my-project/my-metric",
469                     "type": "application/json"
470                   }
471                 },
472                 "_versionId": "version-id-123abc",
473                 "isNumeric": true,
474                 "nameInGroup": "Step 1"
475               }
476             ]
477           }
478         ],
479         "layerSnapshot": {
480           "key": "checkout-flow",
481           "name": "Checkout Flow",
482           "reservationPercent": 10,
483           "otherReservationPercent": 70
484         },
485         "secondaryMetrics": [
486           {
487             "key": "metric-key-123abc",
488             "name": "Example metric",
489             "kind": "pageview",
490             "_links": {
491               "self": {
492                 "href": "/api/v2/metrics/my-project/my-metric",
493                 "type": "application/json"
494               }
495             },
496             "_versionId": "version-id-123abc",
497             "isNumeric": true
498           }
499         ]
500       }
501     ]
502   },
503   "description": "description",
504   "experiments": [
505     {
506       "key": "key",
507       "name": "name",
508       "environment": "environment"
509     }
510   ]
511 }

Create a new holdout in the specified project.

Path parameters

projectKeystringRequired

The project key

environmentKeystringRequired

The environment key

Headers

AuthorizationstringRequired

Request

This endpoint expects an object.

namestringOptional

A human-friendly name for the holdout

keystringOptional

A key that identifies the holdout

descriptionstringOptional

Description of the holdout

randomizationunitstringOptional

The chosen randomization unit for the holdout base experiment

attributeslist of stringsOptional

The attributes that the holdout iteration’s results can be sliced by

holdoutamountstringOptional

Audience allocation for the holdout

primarymetrickeystringOptional

The key of the primary metric for this holdout

metricslist of objectsOptional

Details on the metrics for this experiment

prerequisiteflagkeystringOptional

The key of the flag that the holdout is dependent on

maintainerIdstringOptional

Maintainer id

Response

Holdout response

_idstring

statusenum

Allowed values:

holdoutAmountstring

The percentage of traffic allocated to this holdout.

createdAtlong

updatedAtlong

baseExperimentobject

descriptionstringOptional

experimentslist of objectsOptional

Path parameters

Headers

Request

Response

Errors