Create iteration

Deprecated

POST

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

POST

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

$ curl -X POST https://app.launchdarkly.com/api/v2/projects/projectKey/environments/environmentKey/experiments/experimentKey/iterations \
>      -H "Authorization: <apiKey>" \
>      -H "Content-Type: application/json" \
>      -d '{
>   "hypothesis": "Example hypothesis, the new button placement will increase conversion",
>   "metrics": [
>     {
>       "key": "metric-key-123abc"
>     }
>   ],
>   "treatments": [
>     {
>       "name": "Treatment 1",
>       "baseline": true,
>       "allocationPercent": "10",
>       "parameters": [
>         {
>           "flagKey": "example-flag-for-experiment",
>           "variationId": "e432f62b-55f6-49dd-a02f-eb24acf39d05"
>         }
>       ]
>     }
>   ],
>   "flags": "{\"example-flag-key\": { \"ruleId\": \"e432f62b-55f6-49dd-a02f-eb24acf39d05\", \"flagConfigVersion\": 12, \"notInExperimentVariationId\": \"e432f62b-55f6-49dd-a02f-eb24acf39d05\" }}"
> }'

1 {
2   "hypothesis": "The new button placement will increase conversion",
3   "status": "running",
4   "createdAt": 1654104600000,
5   "_id": "12ab3c45de678910fgh12345",
6   "startedAt": 1655314200000,
7   "endedAt": 1656610200000,
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   "reallocationFrequencyMillis": 3600000,
13   "version": 0,
14   "primaryMetric": {
15     "key": "metric-key-123abc",
16     "_versionId": "string",
17     "name": "My metric",
18     "kind": "custom",
19     "_links": {
20       "self": {
21         "href": "/api/v2/metrics/my-project/my-metric",
22         "type": "application/json"
23       }
24     },
25     "isGroup": true,
26     "isNumeric": true,
27     "eventKey": "event-key-123abc",
28     "metrics": [
29       {
30         "key": "metric-key-123abc",
31         "name": "Example metric",
32         "kind": "custom",
33         "_links": {
34           "self": {
35             "href": "/api/v2/metrics/my-project/my-metric",
36             "type": "application/json"
37           }
38         },
39         "_versionId": "version-id-123abc",
40         "isNumeric": true,
41         "unitAggregationType": "sum",
42         "eventKey": "event-key-123abc",
43         "nameInGroup": "Step 1",
44         "analysisUnits": [
45           "user"
46         ],
47         "randomizationUnits": [
48           "user"
49         ]
50       }
51     ]
52   },
53   "primarySingleMetric": {
54     "key": "metric-key-123abc",
55     "name": "Example metric",
56     "kind": "custom",
57     "_links": {
58       "self": {
59         "href": "/api/v2/metrics/my-project/my-metric",
60         "type": "application/json"
61       }
62     },
63     "_versionId": "version-id-123abc",
64     "isNumeric": true,
65     "unitAggregationType": "sum",
66     "eventKey": "event-key-123abc"
67   },
68   "primaryFunnel": {
69     "key": "metric-group-key-123abc",
70     "name": "My metric group",
71     "kind": "funnel",
72     "_links": {
73       "parent": {
74         "href": "/api/v2/projects/my-project",
75         "type": "application/json"
76       },
77       "self": {
78         "href": "/api/v2/projects/my-project/metric-groups/my-metric-group",
79         "type": "application/json"
80       }
81     },
82     "metrics": [
83       {
84         "key": "metric-key-123abc",
85         "name": "Example metric",
86         "kind": "custom",
87         "_links": {
88           "self": {
89             "href": "/api/v2/metrics/my-project/my-metric",
90             "type": "application/json"
91           }
92         },
93         "_versionId": "version-id-123abc",
94         "isNumeric": true,
95         "unitAggregationType": "sum",
96         "eventKey": "event-key-123abc",
97         "nameInGroup": "Step 1",
98         "analysisUnits": [
99           "user"
100         ],
101         "randomizationUnits": [
102           "user"
103         ]
104       }
105     ]
106   },
107   "randomizationUnit": "user",
108   "attributes": [
109     "string"
110   ],
111   "treatments": [
112     {
113       "name": "Treatment 1",
114       "allocationPercent": "10",
115       "_id": "122c9f3e-da26-4321-ba68-e0fc02eced58",
116       "baseline": true,
117       "parameters": [
118         {
119           "variationId": "string",
120           "flagKey": "string"
121         }
122       ]
123     }
124   ],
125   "metrics": [
126     {
127       "key": "metric-key-123abc",
128       "_versionId": "string",
129       "name": "My metric",
130       "kind": "custom",
131       "_links": {
132         "self": {
133           "href": "/api/v2/metrics/my-project/my-metric",
134           "type": "application/json"
135         }
136       },
137       "isGroup": true,
138       "isNumeric": true,
139       "eventKey": "event-key-123abc",
140       "metrics": [
141         {
142           "key": "metric-key-123abc",
143           "name": "Example metric",
144           "kind": "custom",
145           "_links": {
146             "self": {
147               "href": "/api/v2/metrics/my-project/my-metric",
148               "type": "application/json"
149             }
150           },
151           "_versionId": "version-id-123abc",
152           "isNumeric": true,
153           "unitAggregationType": "sum",
154           "eventKey": "event-key-123abc",
155           "nameInGroup": "Step 1",
156           "analysisUnits": [
157             "user"
158           ],
159           "randomizationUnits": [
160             "user"
161           ]
162         }
163       ]
164     }
165   ],
166   "layerSnapshot": {
167     "key": "checkout-flow",
168     "name": "Checkout Flow",
169     "reservationPercent": 10,
170     "otherReservationPercent": 70
171   },
172   "covariateInfo": {
173     "id": "74a49a2b-4834-4246-917e-5d85231d8c2a",
174     "fileName": "covariate.csv",
175     "createdAt": 1654104600000
176   },
177   "secondaryMetrics": [
178     {
179       "key": "metric-key-123abc",
180       "name": "Example metric",
181       "kind": "custom",
182       "_links": {
183         "self": {
184           "href": "/api/v2/metrics/my-project/my-metric",
185           "type": "application/json"
186         }
187       },
188       "_versionId": "version-id-123abc",
189       "isNumeric": true,
190       "unitAggregationType": "sum",
191       "eventKey": "event-key-123abc"
192     }
193   ]
194 }

> **Deprecated**: This endpoint will be removed in a future version. Use the `updateExperimentFields` and `saveAndStartNewIteration` instructions on [Update experiment](https://launchdarkly.com/docs/api/experiments/patch-experiment) instead. 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](https://launchdarkly.com/docs/api/experiments/patch-experiment) with the `startIteration` or `stopIteration` instruction. To learn more, read [Start experiment iterations](https://launchdarkly.com/docs/home/experimentation/create#start-an-experiment-iteration).

curl -X POST https://app.launchdarkly.com/api/v2/projects/projectKey/environments/environmentKey/experiments/experimentKey/iterations \
     -H "Authorization: <apiKey>" \
     -H "Content-Type: application/json" \
     -d '{
  "hypothesis": "Example hypothesis, the new button placement will increase conversion",
  "metrics": [
    {
      "key": "metric-key-123abc"
    }
  ],
  "treatments": [
    {
      "name": "Treatment 1",
      "baseline": true,
      "allocationPercent": "10",
      "parameters": [
        {
          "flagKey": "example-flag-for-experiment",
          "variationId": "e432f62b-55f6-49dd-a02f-eb24acf39d05"
        }
      ]
    }
  ],
  "flags": "{\"example-flag-key\": { \"ruleId\": \"e432f62b-55f6-49dd-a02f-eb24acf39d05\", \"flagConfigVersion\": 12, \"notInExperimentVariationId\": \"e432f62b-55f6-49dd-a02f-eb24acf39d05\" }}"
}'

{
  "hypothesis": "The new button placement will increase conversion",
  "status": "running",
  "createdAt": 1654104600000,
  "_id": "12ab3c45de678910fgh12345",
  "startedAt": 1655314200000,
  "endedAt": 1656610200000,
  "winningTreatmentId": "122c9f3e-da26-4321-ba68-e0fc02eced58",
  "winningReason": "We ran this iteration for two weeks and the winning variation was clear",
  "canReshuffleTraffic": true,
  "flags": {},
  "reallocationFrequencyMillis": 3600000,
  "version": 0,
  "primaryMetric": {
    "key": "metric-key-123abc",
    "_versionId": "string",
    "name": "My metric",
    "kind": "custom",
    "_links": {
      "self": {
        "href": "/api/v2/metrics/my-project/my-metric",
        "type": "application/json"
      }
    },
    "isGroup": true,
    "isNumeric": true,
    "eventKey": "event-key-123abc",
    "metrics": [
      {
        "key": "metric-key-123abc",
        "name": "Example metric",
        "kind": "custom",
        "_links": {
          "self": {
            "href": "/api/v2/metrics/my-project/my-metric",
            "type": "application/json"
          }
        },
        "_versionId": "version-id-123abc",
        "isNumeric": true,
        "unitAggregationType": "sum",
        "eventKey": "event-key-123abc",
        "nameInGroup": "Step 1",
        "analysisUnits": [
          "user"
        ],
        "randomizationUnits": [
          "user"
        ]
      }
    ]
  },
  "primarySingleMetric": {
    "key": "metric-key-123abc",
    "name": "Example metric",
    "kind": "custom",
    "_links": {
      "self": {
        "href": "/api/v2/metrics/my-project/my-metric",
        "type": "application/json"
      }
    },
    "_versionId": "version-id-123abc",
    "isNumeric": true,
    "unitAggregationType": "sum",
    "eventKey": "event-key-123abc"
  },
  "primaryFunnel": {
    "key": "metric-group-key-123abc",
    "name": "My metric group",
    "kind": "funnel",
    "_links": {
      "parent": {
        "href": "/api/v2/projects/my-project",
        "type": "application/json"
      },
      "self": {
        "href": "/api/v2/projects/my-project/metric-groups/my-metric-group",
        "type": "application/json"
      }
    },
    "metrics": [
      {
        "key": "metric-key-123abc",
        "name": "Example metric",
        "kind": "custom",
        "_links": {
          "self": {
            "href": "/api/v2/metrics/my-project/my-metric",
            "type": "application/json"
          }
        },
        "_versionId": "version-id-123abc",
        "isNumeric": true,
        "unitAggregationType": "sum",
        "eventKey": "event-key-123abc",
        "nameInGroup": "Step 1",
        "analysisUnits": [
          "user"
        ],
        "randomizationUnits": [
          "user"
        ]
      }
    ]
  },
  "randomizationUnit": "user",
  "attributes": [
    "string"
  ],
  "treatments": [
    {
      "name": "Treatment 1",
      "allocationPercent": "10",
      "_id": "122c9f3e-da26-4321-ba68-e0fc02eced58",
      "baseline": true,
      "parameters": [
        {
          "variationId": "string",
          "flagKey": "string"
        }
      ]
    }
  ],
  "metrics": [
    {
      "key": "metric-key-123abc",
      "_versionId": "string",
      "name": "My metric",
      "kind": "custom",
      "_links": {
        "self": {
          "href": "/api/v2/metrics/my-project/my-metric",
          "type": "application/json"
        }
      },
      "isGroup": true,
      "isNumeric": true,
      "eventKey": "event-key-123abc",
      "metrics": [
        {
          "key": "metric-key-123abc",
          "name": "Example metric",
          "kind": "custom",
          "_links": {
            "self": {
              "href": "/api/v2/metrics/my-project/my-metric",
              "type": "application/json"
            }
          },
          "_versionId": "version-id-123abc",
          "isNumeric": true,
          "unitAggregationType": "sum",
          "eventKey": "event-key-123abc",
          "nameInGroup": "Step 1",
          "analysisUnits": [
            "user"
          ],
          "randomizationUnits": [
            "user"
          ]
        }
      ]
    }
  ],
  "layerSnapshot": {
    "key": "checkout-flow",
    "name": "Checkout Flow",
    "reservationPercent": 10,
    "otherReservationPercent": 70
  },
  "covariateInfo": {
    "id": "74a49a2b-4834-4246-917e-5d85231d8c2a",
    "fileName": "covariate.csv",
    "createdAt": 1654104600000
  },
  "secondaryMetrics": [
    {
      "key": "metric-key-123abc",
      "name": "Example metric",
      "kind": "custom",
      "_links": {
        "self": {
          "href": "/api/v2/metrics/my-project/my-metric",
          "type": "application/json"
        }
      },
      "_versionId": "version-id-123abc",
      "isNumeric": true,
      "unitAggregationType": "sum",
      "eventKey": "event-key-123abc"
    }
  ]
}

Deprecated: This endpoint will be removed in a future version. Use the updateExperimentFields and saveAndStartNewIteration instructions on Update experiment instead.

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.

Authentication

Authorizationstring

API Key authentication via header

Path parameters

projectKeystringRequiredformat: "string"

The project key

environmentKeystringRequiredformat: "string"

The environment key

experimentKeystringRequiredformat: "string"

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.

reallocationFrequencyMillisintegerOptional

The cadence (in milliseconds) to update the allocation.

covariateIdstringOptional

The ID of the covariate CSV

attributeslist of stringsOptional

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

Response

Iteration response

hypothesisstring

The expected outcome of this experiment

statusenum

The status of the iteration: not_started, running, stopped

Allowed values:

createdAtlong

Timestamp of when the iteration was created

_idstring

The iteration ID

startedAtlong

Timestamp of when the iteration started

endedAtlong

Timestamp of when the iteration ended

winningTreatmentIdstring

The ID of the treatment chosen when the experiment stopped

winningReasonstring

The reason you stopped the experiment

canReshuffleTrafficboolean

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

Details on the flag used in this experiment

reallocationFrequencyMillisinteger

The cadence (in milliseconds) to update the allocation. Only present for multi-armed bandits.

versioninteger

The current version that the iteration is on

primaryMetricobject

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

primarySingleMetricobject

Details on the primary metric for this experiment

primaryFunnelobject

Details on the primary funnel group for this experiment

randomizationUnitstring

The unit of randomization for this iteration

attributeslist of strings

The available attribute filters for this iteration

treatmentslist of objects

Details on the variations you are testing in the experiment

metricslist of objects

Details on the metrics for this experiment

layerSnapshotobject

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

covariateInfoobject

Details of the covariate file for stratified sampling

secondaryMetricslist of objectsDeprecated

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

Errors

400

Bad Request Error

401

Unauthorized Error

403

Forbidden Error

404

Not Found Error

429

Too Many Requests Error

$	curl -X POST https://app.launchdarkly.com/api/v2/projects/projectKey/environments/environmentKey/experiments/experimentKey/iterations \
>	-H "Authorization: <apiKey>" \
>	-H "Content-Type: application/json" \
>	-d '{
>	"hypothesis": "Example hypothesis, the new button placement will increase conversion",
>	"metrics": [
>	{
>	"key": "metric-key-123abc"
>	}
>	],
>	"treatments": [
>	{
>	"name": "Treatment 1",
>	"baseline": true,
>	"allocationPercent": "10",
>	"parameters": [
>	{
>	"flagKey": "example-flag-for-experiment",
>	"variationId": "e432f62b-55f6-49dd-a02f-eb24acf39d05"
>	}
>	]
>	}
>	],
>	"flags": "{\"example-flag-key\": { \"ruleId\": \"e432f62b-55f6-49dd-a02f-eb24acf39d05\", \"flagConfigVersion\": 12, \"notInExperimentVariationId\": \"e432f62b-55f6-49dd-a02f-eb24acf39d05\" }}"
>	}'

1	{
2	"hypothesis": "The new button placement will increase conversion",
3	"status": "running",
4	"createdAt": 1654104600000,
5	"_id": "12ab3c45de678910fgh12345",
6	"startedAt": 1655314200000,
7	"endedAt": 1656610200000,
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	"reallocationFrequencyMillis": 3600000,
13	"version": 0,
14	"primaryMetric": {
15	"key": "metric-key-123abc",
16	"_versionId": "string",
17	"name": "My metric",
18	"kind": "custom",
19	"_links": {
20	"self": {
21	"href": "/api/v2/metrics/my-project/my-metric",
22	"type": "application/json"
23	}
24	},
25	"isGroup": true,
26	"isNumeric": true,
27	"eventKey": "event-key-123abc",
28	"metrics": [
29	{
30	"key": "metric-key-123abc",
31	"name": "Example metric",
32	"kind": "custom",
33	"_links": {
34	"self": {
35	"href": "/api/v2/metrics/my-project/my-metric",
36	"type": "application/json"
37	}
38	},
39	"_versionId": "version-id-123abc",
40	"isNumeric": true,
41	"unitAggregationType": "sum",
42	"eventKey": "event-key-123abc",
43	"nameInGroup": "Step 1",
44	"analysisUnits": [
45	"user"
46	],
47	"randomizationUnits": [
48	"user"
49	]
50	}
51	]
52	},
53	"primarySingleMetric": {
54	"key": "metric-key-123abc",
55	"name": "Example metric",
56	"kind": "custom",
57	"_links": {
58	"self": {
59	"href": "/api/v2/metrics/my-project/my-metric",
60	"type": "application/json"
61	}
62	},
63	"_versionId": "version-id-123abc",
64	"isNumeric": true,
65	"unitAggregationType": "sum",
66	"eventKey": "event-key-123abc"
67	},
68	"primaryFunnel": {
69	"key": "metric-group-key-123abc",
70	"name": "My metric group",
71	"kind": "funnel",
72	"_links": {
73	"parent": {
74	"href": "/api/v2/projects/my-project",
75	"type": "application/json"
76	},
77	"self": {
78	"href": "/api/v2/projects/my-project/metric-groups/my-metric-group",
79	"type": "application/json"
80	}
81	},
82	"metrics": [
83	{
84	"key": "metric-key-123abc",
85	"name": "Example metric",
86	"kind": "custom",
87	"_links": {
88	"self": {
89	"href": "/api/v2/metrics/my-project/my-metric",
90	"type": "application/json"
91	}
92	},
93	"_versionId": "version-id-123abc",
94	"isNumeric": true,
95	"unitAggregationType": "sum",
96	"eventKey": "event-key-123abc",
97	"nameInGroup": "Step 1",
98	"analysisUnits": [
99	"user"
100	],
101	"randomizationUnits": [
102	"user"
103	]
104	}
105	]
106	},
107	"randomizationUnit": "user",
108	"attributes": [
109	"string"
110	],
111	"treatments": [
112	{
113	"name": "Treatment 1",
114	"allocationPercent": "10",
115	"_id": "122c9f3e-da26-4321-ba68-e0fc02eced58",
116	"baseline": true,
117	"parameters": [
118	{
119	"variationId": "string",
120	"flagKey": "string"
121	}
122	]
123	}
124	],
125	"metrics": [
126	{
127	"key": "metric-key-123abc",
128	"_versionId": "string",
129	"name": "My metric",
130	"kind": "custom",
131	"_links": {
132	"self": {
133	"href": "/api/v2/metrics/my-project/my-metric",
134	"type": "application/json"
135	}
136	},
137	"isGroup": true,
138	"isNumeric": true,
139	"eventKey": "event-key-123abc",
140	"metrics": [
141	{
142	"key": "metric-key-123abc",
143	"name": "Example metric",
144	"kind": "custom",
145	"_links": {
146	"self": {
147	"href": "/api/v2/metrics/my-project/my-metric",
148	"type": "application/json"
149	}
150	},
151	"_versionId": "version-id-123abc",
152	"isNumeric": true,
153	"unitAggregationType": "sum",
154	"eventKey": "event-key-123abc",
155	"nameInGroup": "Step 1",
156	"analysisUnits": [
157	"user"
158	],
159	"randomizationUnits": [
160	"user"
161	]
162	}
163	]
164	}
165	],
166	"layerSnapshot": {
167	"key": "checkout-flow",
168	"name": "Checkout Flow",
169	"reservationPercent": 10,
170	"otherReservationPercent": 70
171	},
172	"covariateInfo": {
173	"id": "74a49a2b-4834-4246-917e-5d85231d8c2a",
174	"fileName": "covariate.csv",
175	"createdAt": 1654104600000
176	},
177	"secondaryMetrics": [
178	{
179	"key": "metric-key-123abc",
180	"name": "Example metric",
181	"kind": "custom",
182	"_links": {
183	"self": {
184	"href": "/api/v2/metrics/my-project/my-metric",
185	"type": "application/json"
186	}
187	},
188	"_versionId": "version-id-123abc",
189	"isNumeric": true,
190	"unitAggregationType": "sum",
191	"eventKey": "event-key-123abc"
192	}
193	]
194	}