Create iteration

POST

/api/v2/projects/:projectKey/environments/:environmentKey/experiments/:experimentKey/iterations

POST

/api/v2/projects/:projectKey/environments/:environmentKey/experiments/:experimentKey/iterations

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

Try it

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 }

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

_idstring or null

The iteration ID

startedAtlong or null

Timestamp of when the iteration started

endedAtlong or null

Timestamp of when the iteration ended

winningTreatmentIdstring or null

The ID of the treatment chosen when the experiment stopped

winningReasonstring or null

The reason you stopped the experiment

canReshuffleTrafficboolean or null

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 objects or null

Details on the flag used in this experiment

primaryMetricobject or null

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

primarySingleMetricobject or null

Details on the primary metric for this experiment

primaryFunnelobject or null

Details on the primary funnel group for this experiment

randomizationUnitstring or null

The unit of randomization for this iteration

attributeslist of strings or null

The available attribute filters for this iteration

treatmentslist of objects or null

Details on the variations you are testing in the experiment

metricslist of objects or null

Details on the metrics for this experiment

layerSnapshotobject or null

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

secondaryMetricslist of objects or nullDeprecated

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

Create iteration

Path parameters

Headers

Request

Response

Errors