Create iteration — LaunchDarkly

Create an experiment iteration.

Experiment iterations let you record experiments in individual blocks of time. Initially, iterations are created with a status of not_started and appear in the draftIteration field of an experiment. To start or stop an iteration, update the experiment with the startIteration or stopIteration instruction.

To learn more, read Start experiment iterations.

Path parameters

projectKeystringRequired

The project key

environmentKeystringRequired

The environment key

experimentKeystringRequired

The experiment key

Request

This endpoint expects an object.

hypothesisstringRequired

The expected outcome of this experiment

metricslist of objectsRequired

Details on the metrics for this experiment

treatmentslist of objectsRequired

Details on the variations you are testing in the experiment. You establish these variations in feature flags, and then reuse them in experiments.

flagsmap from strings to objectsRequired

Details on the feature flag and targeting rules for this iteration

canReshuffleTrafficbooleanOptional

Whether to allow the experiment to reassign traffic to different variations when you increase or decrease the traffic in your experiment audience (true) or keep all traffic assigned to its initial variation (false). Defaults to true.

primarySingleMetricKeystringOptional

The key of the primary metric for this experiment. Either primarySingleMetricKey or primaryFunnelKey must be present.

primaryFunnelKeystringOptional

The key of the primary funnel group for this experiment. Either primarySingleMetricKey or primaryFunnelKey must be present.

randomizationUnitstringOptional

The unit of randomization for this iteration. Defaults to user.

attributeslist of stringsOptional

The attributes that this iteration’s results can be sliced by

Response

Iteration response

hypothesisstring

The expected outcome of this experiment

statusstring

The status of the iteration: not_started, running, stopped

createdAtlong

Timestamp of when the iteration was created

_idstringOptional

The iteration ID

startedAtlongOptional

Timestamp of when the iteration started

endedAtlongOptional

Timestamp of when the iteration ended

winningTreatmentIdstringOptional

The ID of the treatment chosen when the experiment stopped

winningReasonstringOptional

The reason you stopped the experiment

canReshuffleTrafficbooleanOptional

Whether the experiment may reassign traffic to different variations when the experiment audience changes (true) or must keep all traffic assigned to its initial variation (false).

flagsmap from strings to objectsOptional

Details on the flag used in this experiment

primaryMetricobjectOptional

Deprecated, use primarySingleMetric and primaryFunnel instead. Details on the primary metric for this experiment.

primarySingleMetricobjectOptional

Details on the primary metric for this experiment

primaryFunnelobjectOptional

Details on the primary funnel group for this experiment

randomizationUnitstringOptional

The unit of randomization for this iteration

attributeslist of stringsOptional

The available attribute filters for this iteration

treatmentslist of objectsOptional

Details on the variations you are testing in the experiment

metricslist of objectsOptional

Details on the metrics for this experiment

layerSnapshotobjectOptional

Snapshot of the layer state on iteration stop, if part of a layer. Otherwise omitted.

secondaryMetricslist of objectsOptionalDeprecated

Deprecated, use metrics instead. Details on the secondary metrics for this experiment.

Errors

1 curl -X POST https://app.launchdarkly.com/api/v2/projects/projectKey/environments/environmentKey/experiments/experimentKey/iterations \ 2 -H "Authorization: <apiKey>" \ 3 -H "Content-Type: application/json" \ 4 -d '{ 5 "hypothesis": "Example hypothesis, the new button placement will increase conversion", 6 "metrics": [ 7 { 8 "key": "metric-key-123abc" 9 } 10 ], 11 "treatments": [ 12 { 13 "name": "Treatment 1", 14 "baseline": true, 15 "allocationPercent": "10", 16 "parameters": [ 17 { 18 "flagKey": "example-flag-for-experiment", 19 "variationId": "e432f62b-55f6-49dd-a02f-eb24acf39d05" 20 } 21 ] 22 } 23 ], 24 "flags": { 25 "key": { 26 "ruleId": "e432f62b-55f6-49dd-a02f-eb24acf39d05", 27 "flagConfigVersion": 12 28 } 29 } 30 }'

1 { 2 "hypothesis": "The new button placement will increase conversion", 3 "status": "running", 4 "createdAt": 1000000, 5 "_id": "12ab3c45de678910fgh12345", 6 "startedAt": 1000000, 7 "endedAt": 1000000, 8 "winningTreatmentId": "122c9f3e-da26-4321-ba68-e0fc02eced58", 9 "winningReason": "We ran this iteration for two weeks and the winning variation was clear", 10 "canReshuffleTraffic": true, 11 "flags": { 12 "key": { 13 "_links": { 14 "self": { 15 "href": "/api/v2/flags/my-project/my-flag", 16 "type": "application/json" 17 } 18 }, 19 "targetingRule": "fallthrough", 20 "targetingRuleDescription": "Customers who live in Canada", 21 "flagConfigVersion": 12, 22 "notInExperimentVariationId": "e432f62b-55f6-49dd-a02f-eb24acf39d05" 23 } 24 }, 25 "primaryMetric": { 26 "key": "metric-key-123abc", 27 "_versionId": "_versionId", 28 "name": "My metric", 29 "kind": "pageview", 30 "_links": { 31 "self": { 32 "href": "/api/v2/metrics/my-project/my-metric", 33 "type": "application/json" 34 } 35 }, 36 "isGroup": true, 37 "isNumeric": true, 38 "metrics": [ 39 { 40 "key": "metric-key-123abc", 41 "name": "Example metric", 42 "kind": "pageview", 43 "_links": { 44 "self": { 45 "href": "/api/v2/metrics/my-project/my-metric", 46 "type": "application/json" 47 } 48 }, 49 "_versionId": "version-id-123abc", 50 "isNumeric": true, 51 "nameInGroup": "Step 1" 52 } 53 ] 54 }, 55 "primarySingleMetric": { 56 "key": "metric-key-123abc", 57 "name": "Example metric", 58 "kind": "pageview", 59 "_links": { 60 "self": { 61 "href": "/api/v2/metrics/my-project/my-metric", 62 "type": "application/json" 63 } 64 }, 65 "_versionId": "version-id-123abc", 66 "isNumeric": true, 67 "unitAggregationType": "sum" 68 }, 69 "primaryFunnel": { 70 "key": "metric-group-key-123abc", 71 "name": "My metric group", 72 "kind": "funnel", 73 "_links": { 74 "parent": { 75 "href": "/api/v2/projects/my-project", 76 "type": "application/json" 77 }, 78 "self": { 79 "href": "/api/v2/projects/my-project/metric-groups/my-metric-group", 80 "type": "application/json" 81 } 82 }, 83 "metrics": [ 84 { 85 "key": "metric-key-123abc", 86 "name": "Example metric", 87 "kind": "pageview", 88 "_links": { 89 "self": { 90 "href": "/api/v2/metrics/my-project/my-metric", 91 "type": "application/json" 92 } 93 }, 94 "_versionId": "version-id-123abc", 95 "isNumeric": true, 96 "nameInGroup": "Step 1" 97 } 98 ] 99 }, 100 "randomizationUnit": "user", 101 "attributes": [ 102 "attributes" 103 ], 104 "treatments": [ 105 { 106 "name": "Treatment 1", 107 "allocationPercent": "10", 108 "_id": "122c9f3e-da26-4321-ba68-e0fc02eced58", 109 "baseline": true, 110 "parameters": [ 111 {} 112 ] 113 } 114 ], 115 "metrics": [ 116 { 117 "key": "metric-key-123abc", 118 "_versionId": "_versionId", 119 "name": "My metric", 120 "kind": "pageview", 121 "_links": { 122 "self": { 123 "href": "/api/v2/metrics/my-project/my-metric", 124 "type": "application/json" 125 } 126 }, 127 "isGroup": true, 128 "isNumeric": true, 129 "metrics": [ 130 { 131 "key": "metric-key-123abc", 132 "name": "Example metric", 133 "kind": "pageview", 134 "_links": { 135 "self": { 136 "href": "/api/v2/metrics/my-project/my-metric", 137 "type": "application/json" 138 } 139 }, 140 "_versionId": "version-id-123abc", 141 "isNumeric": true, 142 "nameInGroup": "Step 1" 143 } 144 ] 145 } 146 ], 147 "layerSnapshot": { 148 "key": "checkout-flow", 149 "name": "Checkout Flow", 150 "reservationPercent": 10, 151 "otherReservationPercent": 70 152 }, 153 "secondaryMetrics": [ 154 { 155 "key": "metric-key-123abc", 156 "name": "Example metric", 157 "kind": "pageview", 158 "_links": { 159 "self": { 160 "href": "/api/v2/metrics/my-project/my-metric", 161 "type": "application/json" 162 } 163 }, 164 "_versionId": "version-id-123abc", 165 "isNumeric": true, 166 "unitAggregationType": "sum" 167 } 168 ] 169 }

1	curl -X POST https://app.launchdarkly.com/api/v2/projects/projectKey/environments/environmentKey/experiments/experimentKey/iterations \
2	-H "Authorization: <apiKey>" \
3	-H "Content-Type: application/json" \
4	-d '{
5	"hypothesis": "Example hypothesis, the new button placement will increase conversion",
6	"metrics": [
7	{
8	"key": "metric-key-123abc"
9	}
10	],
11	"treatments": [
12	{
13	"name": "Treatment 1",
14	"baseline": true,
15	"allocationPercent": "10",
16	"parameters": [
17	{
18	"flagKey": "example-flag-for-experiment",
19	"variationId": "e432f62b-55f6-49dd-a02f-eb24acf39d05"
20	}
21	]
22	}
23	],
24	"flags": {
25	"key": {
26	"ruleId": "e432f62b-55f6-49dd-a02f-eb24acf39d05",
27	"flagConfigVersion": 12
28	}
29	}
30	}'

1	{
2	"hypothesis": "The new button placement will increase conversion",
3	"status": "running",
4	"createdAt": 1000000,
5	"_id": "12ab3c45de678910fgh12345",
6	"startedAt": 1000000,
7	"endedAt": 1000000,
8	"winningTreatmentId": "122c9f3e-da26-4321-ba68-e0fc02eced58",
9	"winningReason": "We ran this iteration for two weeks and the winning variation was clear",
10	"canReshuffleTraffic": true,
11	"flags": {
12	"key": {
13	"_links": {
14	"self": {
15	"href": "/api/v2/flags/my-project/my-flag",
16	"type": "application/json"
17	}
18	},
19	"targetingRule": "fallthrough",
20	"targetingRuleDescription": "Customers who live in Canada",
21	"flagConfigVersion": 12,
22	"notInExperimentVariationId": "e432f62b-55f6-49dd-a02f-eb24acf39d05"
23	}
24	},
25	"primaryMetric": {
26	"key": "metric-key-123abc",
27	"_versionId": "_versionId",
28	"name": "My metric",
29	"kind": "pageview",
30	"_links": {
31	"self": {
32	"href": "/api/v2/metrics/my-project/my-metric",
33	"type": "application/json"
34	}
35	},
36	"isGroup": true,
37	"isNumeric": true,
38	"metrics": [
39	{
40	"key": "metric-key-123abc",
41	"name": "Example metric",
42	"kind": "pageview",
43	"_links": {
44	"self": {
45	"href": "/api/v2/metrics/my-project/my-metric",
46	"type": "application/json"
47	}
48	},
49	"_versionId": "version-id-123abc",
50	"isNumeric": true,
51	"nameInGroup": "Step 1"
52	}
53	]
54	},
55	"primarySingleMetric": {
56	"key": "metric-key-123abc",
57	"name": "Example metric",
58	"kind": "pageview",
59	"_links": {
60	"self": {
61	"href": "/api/v2/metrics/my-project/my-metric",
62	"type": "application/json"
63	}
64	},
65	"_versionId": "version-id-123abc",
66	"isNumeric": true,
67	"unitAggregationType": "sum"
68	},
69	"primaryFunnel": {
70	"key": "metric-group-key-123abc",
71	"name": "My metric group",
72	"kind": "funnel",
73	"_links": {
74	"parent": {
75	"href": "/api/v2/projects/my-project",
76	"type": "application/json"
77	},
78	"self": {
79	"href": "/api/v2/projects/my-project/metric-groups/my-metric-group",
80	"type": "application/json"
81	}
82	},
83	"metrics": [
84	{
85	"key": "metric-key-123abc",
86	"name": "Example metric",
87	"kind": "pageview",
88	"_links": {
89	"self": {
90	"href": "/api/v2/metrics/my-project/my-metric",
91	"type": "application/json"
92	}
93	},
94	"_versionId": "version-id-123abc",
95	"isNumeric": true,
96	"nameInGroup": "Step 1"
97	}
98	]
99	},
100	"randomizationUnit": "user",
101	"attributes": [
102	"attributes"
103	],
104	"treatments": [
105	{
106	"name": "Treatment 1",
107	"allocationPercent": "10",
108	"_id": "122c9f3e-da26-4321-ba68-e0fc02eced58",
109	"baseline": true,
110	"parameters": [
111	{}
112	]
113	}
114	],
115	"metrics": [
116	{
117	"key": "metric-key-123abc",
118	"_versionId": "_versionId",
119	"name": "My metric",
120	"kind": "pageview",
121	"_links": {
122	"self": {
123	"href": "/api/v2/metrics/my-project/my-metric",
124	"type": "application/json"
125	}
126	},
127	"isGroup": true,
128	"isNumeric": true,
129	"metrics": [
130	{
131	"key": "metric-key-123abc",
132	"name": "Example metric",
133	"kind": "pageview",
134	"_links": {
135	"self": {
136	"href": "/api/v2/metrics/my-project/my-metric",
137	"type": "application/json"
138	}
139	},
140	"_versionId": "version-id-123abc",
141	"isNumeric": true,
142	"nameInGroup": "Step 1"
143	}
144	]
145	}
146	],
147	"layerSnapshot": {
148	"key": "checkout-flow",
149	"name": "Checkout Flow",
150	"reservationPercent": 10,
151	"otherReservationPercent": 70
152	},
153	"secondaryMetrics": [
154	{
155	"key": "metric-key-123abc",
156	"name": "Example metric",
157	"kind": "pageview",
158	"_links": {
159	"self": {
160	"href": "/api/v2/metrics/my-project/my-metric",
161	"type": "application/json"
162	}
163	},
164	"_versionId": "version-id-123abc",
165	"isNumeric": true,
166	"unitAggregationType": "sum"
167	}
168	]
169	}