For AI agents: a documentation index is available at the root level at /llms.txt and /llms-full.txt. Append /llms.txt to any URL for a page-level index, or .md for the markdown version of any page.
Sign inTry it free
DocsGuidesSDKsIntegrationsAPI docsTutorialsFlagship blog
DocsGuidesSDKsIntegrationsAPI docsTutorialsFlagship blog
  • REST API overview
    • Access Tokens
    • Account Members
    • Account Usage Beta
    • AI Configs
    • Announcements
    • Applications Beta
    • Approvals
    • Approvals Beta
    • Audit Log
    • Code References
    • Contexts
    • Context Settings
    • Custom Roles
    • Data Export Destinations
    • Environments
    • Experiments
      • POSTCreate experiment
      • POSTCreate iteration
      • GETGet experiment
      • GETGet experimentation settings
      • GETGet experiments
      • GETGet experiments any environment
      • PATCHPatch experiment
      • PUTUpdate experimentation settings
    • Feature Flags
    • Feature Flags Beta
    • Flag Import Configurations Beta
    • Flag Links Beta
    • Flag Triggers
    • Follow Flags
    • Holdouts Beta
    • Insights Charts Beta
    • Insights Deployments Beta
    • Insights Flag Events Beta
    • Insights Pull Requests Beta
    • Insights Repositories Beta
    • Insights Scores Beta
    • Integration Audit Log Subscriptions
    • Integration Delivery Configurations Beta
    • Integrations Beta
    • Layers
    • Metrics
    • Metrics Beta
    • OAuth2 Clients
    • Persistent Store Integrations Beta
    • Projects
    • Relay Proxy Configurations
    • Release Pipelines Beta
    • Releases Beta
    • Scheduled Changes
    • Segments
    • Tags
    • Teams
    • Teams Beta
    • Users
    • Users Beta
    • User Settings
    • Views Beta
    • Webhooks
    • Workflows
    • Workflow Templates
    • Other
Sign inTry it free
LogoLogo
REST API overviewExperiments

Create experiment

POST
/api/v2/projects/:projectKey/environments/:environmentKey/experiments
POST
/api/v2/projects/:projectKey/environments/:environmentKey/experiments
$curl -X POST https://app.launchdarkly.com/api/v2/projects/projectKey/environments/environmentKey/experiments \
> -H "Authorization: <apiKey>" \
> -H "Content-Type: application/json" \
> -d '{
> "name": "Example experiment",
> "key": "experiment-key-123abc",
> "iteration": {
> "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 "key": "experiment-key-123abc",
3 "name": "Example experiment",
4 "_maintainerId": "12ab3c45de678910fgh12345",
5 "_creationDate": 1654104600000,
6 "environmentKey": "string",
7 "_links": {
8 "parent": {
9 "href": "/api/v2/projects/my-project/environments/my-environment",
10 "type": "application/json"
11 },
12 "self": {
13 "href": "/api/v2/projects/my-project/environments/my-environment/experiments/my-experiment",
14 "type": "application/json"
15 }
16 },
17 "_id": "12ab3c45de678910fgh12345",
18 "description": "An example experiment, used in testing",
19 "methodology": "bayesian",
20 "dataSource": "snowflake",
21 "archivedDate": 1654104600000,
22 "tags": [
23 "experiment",
24 "feature"
25 ],
26 "holdoutId": "f3b74309-d581-44e1-8a2b-bb2933b4fe40",
27 "currentIteration": {
28 "hypothesis": "The new button placement will increase conversion",
29 "status": "running",
30 "createdAt": 1654104600000,
31 "_id": "12ab3c45de678910fgh12345",
32 "startedAt": 1655314200000,
33 "endedAt": 1656610200000,
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 "reallocationFrequencyMillis": 3600000,
39 "version": 0,
40 "primaryMetric": {
41 "key": "metric-key-123abc",
42 "_versionId": "string",
43 "name": "My metric",
44 "kind": "custom",
45 "_links": {
46 "self": {
47 "href": "/api/v2/metrics/my-project/my-metric",
48 "type": "application/json"
49 }
50 },
51 "isGroup": true,
52 "isNumeric": true,
53 "eventKey": "event-key-123abc",
54 "metrics": [
55 {
56 "key": "metric-key-123abc",
57 "name": "Example metric",
58 "kind": "custom",
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 "eventKey": "event-key-123abc",
69 "nameInGroup": "Step 1",
70 "analysisUnits": [
71 "user"
72 ],
73 "randomizationUnits": [
74 "user"
75 ]
76 }
77 ]
78 },
79 "primarySingleMetric": {
80 "key": "metric-key-123abc",
81 "name": "Example metric",
82 "kind": "custom",
83 "_links": {
84 "self": {
85 "href": "/api/v2/metrics/my-project/my-metric",
86 "type": "application/json"
87 }
88 },
89 "_versionId": "version-id-123abc",
90 "isNumeric": true,
91 "unitAggregationType": "sum",
92 "eventKey": "event-key-123abc"
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": "custom",
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 "unitAggregationType": "sum",
122 "eventKey": "event-key-123abc",
123 "nameInGroup": "Step 1",
124 "analysisUnits": [
125 "user"
126 ],
127 "randomizationUnits": [
128 "user"
129 ]
130 }
131 ]
132 },
133 "randomizationUnit": "user",
134 "attributes": [
135 "string"
136 ],
137 "treatments": [
138 {
139 "name": "Treatment 1",
140 "allocationPercent": "10",
141 "_id": "122c9f3e-da26-4321-ba68-e0fc02eced58",
142 "baseline": true,
143 "parameters": [
144 {
145 "variationId": "string",
146 "flagKey": "string"
147 }
148 ]
149 }
150 ],
151 "metrics": [
152 {
153 "key": "metric-key-123abc",
154 "_versionId": "string",
155 "name": "My metric",
156 "kind": "custom",
157 "_links": {
158 "self": {
159 "href": "/api/v2/metrics/my-project/my-metric",
160 "type": "application/json"
161 }
162 },
163 "isGroup": true,
164 "isNumeric": true,
165 "eventKey": "event-key-123abc",
166 "metrics": [
167 {
168 "key": "metric-key-123abc",
169 "name": "Example metric",
170 "kind": "custom",
171 "_links": {
172 "self": {
173 "href": "/api/v2/metrics/my-project/my-metric",
174 "type": "application/json"
175 }
176 },
177 "_versionId": "version-id-123abc",
178 "isNumeric": true,
179 "unitAggregationType": "sum",
180 "eventKey": "event-key-123abc",
181 "nameInGroup": "Step 1",
182 "analysisUnits": [
183 "user"
184 ],
185 "randomizationUnits": [
186 "user"
187 ]
188 }
189 ]
190 }
191 ],
192 "layerSnapshot": {
193 "key": "checkout-flow",
194 "name": "Checkout Flow",
195 "reservationPercent": 10,
196 "otherReservationPercent": 70
197 },
198 "covariateInfo": {
199 "id": "74a49a2b-4834-4246-917e-5d85231d8c2a",
200 "fileName": "covariate.csv",
201 "createdAt": 1654104600000
202 },
203 "secondaryMetrics": [
204 {
205 "key": "metric-key-123abc",
206 "name": "Example metric",
207 "kind": "custom",
208 "_links": {
209 "self": {
210 "href": "/api/v2/metrics/my-project/my-metric",
211 "type": "application/json"
212 }
213 },
214 "_versionId": "version-id-123abc",
215 "isNumeric": true,
216 "unitAggregationType": "sum",
217 "eventKey": "event-key-123abc"
218 }
219 ]
220 },
221 "type": "experiment",
222 "draftIteration": {
223 "hypothesis": "The new button placement will increase conversion",
224 "status": "running",
225 "createdAt": 1654104600000,
226 "_id": "12ab3c45de678910fgh12345",
227 "startedAt": 1655314200000,
228 "endedAt": 1656610200000,
229 "winningTreatmentId": "122c9f3e-da26-4321-ba68-e0fc02eced58",
230 "winningReason": "We ran this iteration for two weeks and the winning variation was clear",
231 "canReshuffleTraffic": true,
232 "flags": {},
233 "reallocationFrequencyMillis": 3600000,
234 "version": 0,
235 "primaryMetric": {
236 "key": "metric-key-123abc",
237 "_versionId": "string",
238 "name": "My metric",
239 "kind": "custom",
240 "_links": {
241 "self": {
242 "href": "/api/v2/metrics/my-project/my-metric",
243 "type": "application/json"
244 }
245 },
246 "isGroup": true,
247 "isNumeric": true,
248 "eventKey": "event-key-123abc",
249 "metrics": [
250 {
251 "key": "metric-key-123abc",
252 "name": "Example metric",
253 "kind": "custom",
254 "_links": {
255 "self": {
256 "href": "/api/v2/metrics/my-project/my-metric",
257 "type": "application/json"
258 }
259 },
260 "_versionId": "version-id-123abc",
261 "isNumeric": true,
262 "unitAggregationType": "sum",
263 "eventKey": "event-key-123abc",
264 "nameInGroup": "Step 1",
265 "analysisUnits": [
266 "user"
267 ],
268 "randomizationUnits": [
269 "user"
270 ]
271 }
272 ]
273 },
274 "primarySingleMetric": {
275 "key": "metric-key-123abc",
276 "name": "Example metric",
277 "kind": "custom",
278 "_links": {
279 "self": {
280 "href": "/api/v2/metrics/my-project/my-metric",
281 "type": "application/json"
282 }
283 },
284 "_versionId": "version-id-123abc",
285 "isNumeric": true,
286 "unitAggregationType": "sum",
287 "eventKey": "event-key-123abc"
288 },
289 "primaryFunnel": {
290 "key": "metric-group-key-123abc",
291 "name": "My metric group",
292 "kind": "funnel",
293 "_links": {
294 "parent": {
295 "href": "/api/v2/projects/my-project",
296 "type": "application/json"
297 },
298 "self": {
299 "href": "/api/v2/projects/my-project/metric-groups/my-metric-group",
300 "type": "application/json"
301 }
302 },
303 "metrics": [
304 {
305 "key": "metric-key-123abc",
306 "name": "Example metric",
307 "kind": "custom",
308 "_links": {
309 "self": {
310 "href": "/api/v2/metrics/my-project/my-metric",
311 "type": "application/json"
312 }
313 },
314 "_versionId": "version-id-123abc",
315 "isNumeric": true,
316 "unitAggregationType": "sum",
317 "eventKey": "event-key-123abc",
318 "nameInGroup": "Step 1",
319 "analysisUnits": [
320 "user"
321 ],
322 "randomizationUnits": [
323 "user"
324 ]
325 }
326 ]
327 },
328 "randomizationUnit": "user",
329 "attributes": [
330 "string"
331 ],
332 "treatments": [
333 {
334 "name": "Treatment 1",
335 "allocationPercent": "10",
336 "_id": "122c9f3e-da26-4321-ba68-e0fc02eced58",
337 "baseline": true,
338 "parameters": [
339 {
340 "variationId": "string",
341 "flagKey": "string"
342 }
343 ]
344 }
345 ],
346 "metrics": [
347 {
348 "key": "metric-key-123abc",
349 "_versionId": "string",
350 "name": "My metric",
351 "kind": "custom",
352 "_links": {
353 "self": {
354 "href": "/api/v2/metrics/my-project/my-metric",
355 "type": "application/json"
356 }
357 },
358 "isGroup": true,
359 "isNumeric": true,
360 "eventKey": "event-key-123abc",
361 "metrics": [
362 {
363 "key": "metric-key-123abc",
364 "name": "Example metric",
365 "kind": "custom",
366 "_links": {
367 "self": {
368 "href": "/api/v2/metrics/my-project/my-metric",
369 "type": "application/json"
370 }
371 },
372 "_versionId": "version-id-123abc",
373 "isNumeric": true,
374 "unitAggregationType": "sum",
375 "eventKey": "event-key-123abc",
376 "nameInGroup": "Step 1",
377 "analysisUnits": [
378 "user"
379 ],
380 "randomizationUnits": [
381 "user"
382 ]
383 }
384 ]
385 }
386 ],
387 "layerSnapshot": {
388 "key": "checkout-flow",
389 "name": "Checkout Flow",
390 "reservationPercent": 10,
391 "otherReservationPercent": 70
392 },
393 "covariateInfo": {
394 "id": "74a49a2b-4834-4246-917e-5d85231d8c2a",
395 "fileName": "covariate.csv",
396 "createdAt": 1654104600000
397 },
398 "secondaryMetrics": [
399 {
400 "key": "metric-key-123abc",
401 "name": "Example metric",
402 "kind": "custom",
403 "_links": {
404 "self": {
405 "href": "/api/v2/metrics/my-project/my-metric",
406 "type": "application/json"
407 }
408 },
409 "_versionId": "version-id-123abc",
410 "isNumeric": true,
411 "unitAggregationType": "sum",
412 "eventKey": "event-key-123abc"
413 }
414 ]
415 },
416 "previousIterations": [
417 {
418 "hypothesis": "The new button placement will increase conversion",
419 "status": "running",
420 "createdAt": 1654104600000,
421 "_id": "12ab3c45de678910fgh12345",
422 "startedAt": 1655314200000,
423 "endedAt": 1656610200000,
424 "winningTreatmentId": "122c9f3e-da26-4321-ba68-e0fc02eced58",
425 "winningReason": "We ran this iteration for two weeks and the winning variation was clear",
426 "canReshuffleTraffic": true,
427 "flags": {},
428 "reallocationFrequencyMillis": 3600000,
429 "version": 0,
430 "primaryMetric": {
431 "key": "metric-key-123abc",
432 "_versionId": "string",
433 "name": "My metric",
434 "kind": "custom",
435 "_links": {
436 "self": {
437 "href": "/api/v2/metrics/my-project/my-metric",
438 "type": "application/json"
439 }
440 },
441 "isGroup": true,
442 "isNumeric": true,
443 "eventKey": "event-key-123abc",
444 "metrics": [
445 {
446 "key": "metric-key-123abc",
447 "name": "Example metric",
448 "kind": "custom",
449 "_links": {
450 "self": {
451 "href": "/api/v2/metrics/my-project/my-metric",
452 "type": "application/json"
453 }
454 },
455 "_versionId": "version-id-123abc",
456 "isNumeric": true,
457 "unitAggregationType": "sum",
458 "eventKey": "event-key-123abc",
459 "nameInGroup": "Step 1",
460 "analysisUnits": [
461 "user"
462 ],
463 "randomizationUnits": [
464 "user"
465 ]
466 }
467 ]
468 },
469 "primarySingleMetric": {
470 "key": "metric-key-123abc",
471 "name": "Example metric",
472 "kind": "custom",
473 "_links": {
474 "self": {
475 "href": "/api/v2/metrics/my-project/my-metric",
476 "type": "application/json"
477 }
478 },
479 "_versionId": "version-id-123abc",
480 "isNumeric": true,
481 "unitAggregationType": "sum",
482 "eventKey": "event-key-123abc"
483 },
484 "primaryFunnel": {
485 "key": "metric-group-key-123abc",
486 "name": "My metric group",
487 "kind": "funnel",
488 "_links": {
489 "parent": {
490 "href": "/api/v2/projects/my-project",
491 "type": "application/json"
492 },
493 "self": {
494 "href": "/api/v2/projects/my-project/metric-groups/my-metric-group",
495 "type": "application/json"
496 }
497 },
498 "metrics": [
499 {
500 "key": "metric-key-123abc",
501 "name": "Example metric",
502 "kind": "custom",
503 "_links": {
504 "self": {
505 "href": "/api/v2/metrics/my-project/my-metric",
506 "type": "application/json"
507 }
508 },
509 "_versionId": "version-id-123abc",
510 "isNumeric": true,
511 "unitAggregationType": "sum",
512 "eventKey": "event-key-123abc",
513 "nameInGroup": "Step 1",
514 "analysisUnits": [
515 "user"
516 ],
517 "randomizationUnits": [
518 "user"
519 ]
520 }
521 ]
522 },
523 "randomizationUnit": "user",
524 "attributes": [
525 "string"
526 ],
527 "treatments": [
528 {
529 "name": "Treatment 1",
530 "allocationPercent": "10",
531 "_id": "122c9f3e-da26-4321-ba68-e0fc02eced58",
532 "baseline": true,
533 "parameters": [
534 {
535 "variationId": "string",
536 "flagKey": "string"
537 }
538 ]
539 }
540 ],
541 "metrics": [
542 {
543 "key": "metric-key-123abc",
544 "_versionId": "string",
545 "name": "My metric",
546 "kind": "custom",
547 "_links": {
548 "self": {
549 "href": "/api/v2/metrics/my-project/my-metric",
550 "type": "application/json"
551 }
552 },
553 "isGroup": true,
554 "isNumeric": true,
555 "eventKey": "event-key-123abc",
556 "metrics": [
557 {
558 "key": "metric-key-123abc",
559 "name": "Example metric",
560 "kind": "custom",
561 "_links": {
562 "self": {
563 "href": "/api/v2/metrics/my-project/my-metric",
564 "type": "application/json"
565 }
566 },
567 "_versionId": "version-id-123abc",
568 "isNumeric": true,
569 "unitAggregationType": "sum",
570 "eventKey": "event-key-123abc",
571 "nameInGroup": "Step 1",
572 "analysisUnits": [
573 "user"
574 ],
575 "randomizationUnits": [
576 "user"
577 ]
578 }
579 ]
580 }
581 ],
582 "layerSnapshot": {
583 "key": "checkout-flow",
584 "name": "Checkout Flow",
585 "reservationPercent": 10,
586 "otherReservationPercent": 70
587 },
588 "covariateInfo": {
589 "id": "74a49a2b-4834-4246-917e-5d85231d8c2a",
590 "fileName": "covariate.csv",
591 "createdAt": 1654104600000
592 },
593 "secondaryMetrics": [
594 {
595 "key": "metric-key-123abc",
596 "name": "Example metric",
597 "kind": "custom",
598 "_links": {
599 "self": {
600 "href": "/api/v2/metrics/my-project/my-metric",
601 "type": "application/json"
602 }
603 },
604 "_versionId": "version-id-123abc",
605 "isNumeric": true,
606 "unitAggregationType": "sum",
607 "eventKey": "event-key-123abc"
608 }
609 ]
610 }
611 ],
612 "analysisConfig": {
613 "bayesianThreshold": "string",
614 "significanceThreshold": "string",
615 "testDirection": "string",
616 "multipleComparisonCorrectionMethod": "bonferroni",
617 "multipleComparisonCorrectionScope": "variations",
618 "sequentialTestingEnabled": true
619 },
620 "mutableFieldsByStatus": {
621 "not_started": {},
622 "running": {},
623 "stopped": {}
624 }
625}
Create an experiment. To run this experiment, you'll need to [create an iteration](https://launchdarkly.com/docs/api/experiments/create-iteration) and then [update the experiment](https://launchdarkly.com/docs/api/experiments/patch-experiment) with the `startIteration` instruction. ### Experiment types Use the `type` field to specify the experiment type: `experiment` (default), `mab` (multi-armed bandit), or `holdout`. For multi-armed bandit experiments, set `reallocationFrequencyMillis` on the iteration to control how often traffic is reallocated across variations. ### Results analysis Use the `methodology` field to specify the results analysis approach: `bayesian` (default) or `frequentist`. Use the `dataSource` field to specify the source of metric data: `launchdarkly` (default), `snowflake`, or `databricks`. Use the `analysisConfig` field to customize analysis settings such as the Bayesian threshold, significance threshold, or multiple comparison correction method. To learn more, read [Creating experiments](https://launchdarkly.com/docs/home/experimentation/create).
Was this page helpful?
Previous

Create iteration

Next
Built with

Create an experiment.

To run this experiment, you’ll need to create an iteration and then update the experiment with the startIteration instruction.

Experiment types

Use the type field to specify the experiment type: experiment (default), mab (multi-armed bandit), or holdout.

For multi-armed bandit experiments, set reallocationFrequencyMillis on the iteration to control how often traffic is reallocated across variations.

Results analysis

Use the methodology field to specify the results analysis approach: bayesian (default) or frequentist.

Use the dataSource field to specify the source of metric data: launchdarkly (default), snowflake, or databricks.

Use the analysisConfig field to customize analysis settings such as the Bayesian threshold, significance threshold, or multiple comparison correction method.

To learn more, read Creating experiments.

Authentication

Authorizationstring
API Key authentication via header

Path parameters

projectKeystringRequiredformat: "string"
The project key
environmentKeystringRequiredformat: "string"
The environment key

Request

This endpoint expects an object.
namestringRequired
The experiment name
keystringRequired
The experiment key
iterationobjectRequired
Details on the construction of the initial iteration
descriptionstringOptional
The experiment description
maintainerIdstringOptional
The ID of the member who maintains this experiment
holdoutIdstringOptional
The ID of the holdout
tagslist of stringsOptional
Tags for the experiment
methodologyenumOptional
The results analysis approach.
Allowed values:
analysisConfigobjectOptional
Details of the Analysis Configuration for this experiment
dataSourceenumOptional
The source of metric data in order to analyze results. Defaults to "launchdarkly" when not provided.
Allowed values:
typeenumOptional
The type of experiment.
Allowed values:

Response

Experiment response
keystring
The experiment key
namestring
The experiment name
_maintainerIdstring
The ID of the member who maintains this experiment.
_creationDatelong
Timestamp of when the experiment was created
environmentKeystring
_linksmap from strings to objects
The location and content type of related resources
_idstring
The experiment ID
descriptionstring
The experiment description
methodologyenum
The results analysis approach.
Allowed values:
dataSourceenum
The source of metric data in order to analyze results. Defaults to "launchdarkly" when not provided.
Allowed values:
archivedDatelong
Timestamp of when the experiment was archived
tagslist of strings
Tags for the experiment
holdoutIdstring
The holdout ID
currentIterationobject
Details on the current iteration
typestring
The experiment type
draftIterationobject
Details on the current iteration. This iteration may be already started, or may still be a draft.
previousIterationslist of objects
Details on the previous iterations for this experiment.
analysisConfigobject
Details of the Analysis Configuration for this experiment.
mutableFieldsByStatusobject
Fields that can be changed for each iteration status.

Errors

400
Bad Request Error
401
Unauthorized Error
403
Forbidden Error
404
Not Found Error
429
Too Many Requests Error