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\" }}"
  }
}'

{
  "key": "experiment-key-123abc",
  "name": "Example experiment",
  "_maintainerId": "12ab3c45de678910fgh12345",
  "_creationDate": 1654104600000,
  "environmentKey": "string",
  "_links": {
    "parent": {
      "href": "/api/v2/projects/my-project/environments/my-environment",
      "type": "application/json"
    },
    "self": {
      "href": "/api/v2/projects/my-project/environments/my-environment/experiments/my-experiment",
      "type": "application/json"
    }
  },
  "_id": "12ab3c45de678910fgh12345",
  "description": "An example experiment, used in testing",
  "methodology": "bayesian",
  "dataSource": "snowflake",
  "archivedDate": 1654104600000,
  "tags": [
    "experiment",
    "feature"
  ],
  "holdoutId": "f3b74309-d581-44e1-8a2b-bb2933b4fe40",
  "currentIteration": {
    "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",
          "analysisType": "mean",
          "eventKey": "event-key-123abc",
          "analysisUnit": "string",
          "nameInGroup": "Step 1",
          "analysisUnits": [
            "user"
          ],
          "randomizationUnits": [
            "user"
          ]
        }
      ],
      "analysisType": "mean",
      "analysisUnit": "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",
      "analysisType": "mean",
      "eventKey": "event-key-123abc",
      "analysisUnit": "string"
    },
    "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",
          "analysisType": "mean",
          "eventKey": "event-key-123abc",
          "analysisUnit": "string",
          "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",
            "analysisType": "mean",
            "eventKey": "event-key-123abc",
            "analysisUnit": "string",
            "nameInGroup": "Step 1",
            "analysisUnits": [
              "user"
            ],
            "randomizationUnits": [
              "user"
            ]
          }
        ],
        "analysisType": "mean",
        "analysisUnit": "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",
        "analysisType": "mean",
        "eventKey": "event-key-123abc",
        "analysisUnit": "string"
      }
    ]
  },
  "type": "experiment",
  "_access": {
    "denied": [
      {
        "action": "string",
        "reason": {
          "effect": "allow",
          "resources": [
            "proj/*:env/*;qa_*:/flag/*"
          ],
          "notResources": [
            "string"
          ],
          "actions": [
            "*"
          ],
          "notActions": [
            "string"
          ],
          "role_name": "string"
        }
      }
    ],
    "allowed": [
      {
        "action": "string",
        "reason": {
          "effect": "allow",
          "resources": [
            "proj/*:env/*;qa_*:/flag/*"
          ],
          "notResources": [
            "string"
          ],
          "actions": [
            "*"
          ],
          "notActions": [
            "string"
          ],
          "role_name": "string"
        }
      }
    ]
  },
  "draftIteration": {
    "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",
          "analysisType": "mean",
          "eventKey": "event-key-123abc",
          "analysisUnit": "string",
          "nameInGroup": "Step 1",
          "analysisUnits": [
            "user"
          ],
          "randomizationUnits": [
            "user"
          ]
        }
      ],
      "analysisType": "mean",
      "analysisUnit": "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",
      "analysisType": "mean",
      "eventKey": "event-key-123abc",
      "analysisUnit": "string"
    },
    "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",
          "analysisType": "mean",
          "eventKey": "event-key-123abc",
          "analysisUnit": "string",
          "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",
            "analysisType": "mean",
            "eventKey": "event-key-123abc",
            "analysisUnit": "string",
            "nameInGroup": "Step 1",
            "analysisUnits": [
              "user"
            ],
            "randomizationUnits": [
              "user"
            ]
          }
        ],
        "analysisType": "mean",
        "analysisUnit": "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",
        "analysisType": "mean",
        "eventKey": "event-key-123abc",
        "analysisUnit": "string"
      }
    ]
  },
  "previousIterations": [
    {
      "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",
            "analysisType": "mean",
            "eventKey": "event-key-123abc",
            "analysisUnit": "string",
            "nameInGroup": "Step 1",
            "analysisUnits": [
              "user"
            ],
            "randomizationUnits": [
              "user"
            ]
          }
        ],
        "analysisType": "mean",
        "analysisUnit": "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",
        "analysisType": "mean",
        "eventKey": "event-key-123abc",
        "analysisUnit": "string"
      },
      "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",
            "analysisType": "mean",
            "eventKey": "event-key-123abc",
            "analysisUnit": "string",
            "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",
              "analysisType": "mean",
              "eventKey": "event-key-123abc",
              "analysisUnit": "string",
              "nameInGroup": "Step 1",
              "analysisUnits": [
                "user"
              ],
              "randomizationUnits": [
                "user"
              ]
            }
          ],
          "analysisType": "mean",
          "analysisUnit": "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",
          "analysisType": "mean",
          "eventKey": "event-key-123abc",
          "analysisUnit": "string"
        }
      ]
    }
  ],
  "analysisConfig": {
    "bayesianThreshold": "string",
    "significanceThreshold": "string",
    "testDirection": "string",
    "multipleComparisonCorrectionMethod": "bonferroni",
    "multipleComparisonCorrectionScope": "variations",
    "sequentialTestingEnabled": true
  },
  "mutableFieldsByStatus": {
    "not_started": {},
    "running": {},
    "stopped": {}
  }
}

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.

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).

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

_idstringOptional

The experiment ID

descriptionstringOptional

The experiment description

methodologyenumOptional

The results analysis approach.

Allowed values:

dataSourceenumOptional

The source of metric data in order to analyze results. Defaults to "launchdarkly" when not provided.

Allowed values:

archivedDatelongOptional

Timestamp of when the experiment was archived

tagslist of stringsOptional

Tags for the experiment

holdoutIdstringOptional

The holdout ID

currentIterationobjectOptional

Details on the current iteration

typestringOptional

The experiment type

_accessobjectOptional

Details on the allowed and denied actions for this experiment

draftIterationobjectOptional

Details on the current iteration. This iteration may be already started, or may still be a draft.

previousIterationslist of objectsOptional

Details on the previous iterations for this experiment.

analysisConfigobjectOptional

Details of the Analysis Configuration for this experiment.

mutableFieldsByStatusobjectOptional

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