Create iteration

For the complete documentation index, see llms.txt. For the full documentation snapshot, see llms-full.txt.

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.

POST /api/v2/projects/{projectKey}/environments/{environmentKey}/experiments/{experimentKey}/iterations

Create iteration

cURL

curl --request POST \
  --url https://app.launchdarkly.com/api/v2/projects/{projectKey}/environments/{environmentKey}/experiments/{experimentKey}/iterations \
  --header 'Authorization: <api-key>' \
  --header 'Content-Type: application/json' \
  --data '
{
  "hypothesis": "Example hypothesis, the new button placement will increase conversion",
  "metrics": [
    {
      "key": "metric-key-123abc",
      "isGroup": true,
      "primary": true
    }
  ],
  "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\" }}",
  "canReshuffleTraffic": true,
  "primarySingleMetricKey": "metric-key-123abc",
  "primaryFunnelKey": "metric-group-key-123abc",
  "randomizationUnit": "user",
  "reallocationFrequencyMillis": 3600000,
  "covariateId": "<string>",
  "attributes": [
    "country",
    "device",
    "os"
  ]
}
'

200

{
  "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",
        "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",
        "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>"
        }
      ]
    }
  ],
  "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"
    }
  ],
  "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",
          "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"
  }
}

Authorizations

Authorization · string · header · required

Path Parameters

projectKey · string<string> · required

The project key

environmentKey · string<string> · required

The environment key

experimentKey · string<string> · required

The experiment key

Body

application/json

hypothesis · string · required

The expected outcome of this experiment

Example:

"Example hypothesis, the new button placement will increase conversion"

metrics · object[] · required

Details on the metrics for this experiment

Show child attributes

treatments · object[] · required

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

Show child attributes

flags · object · required

Details on the feature flag and targeting rules for this iteration

Show child attributes

Example:

"{\"example-flag-key\": { \"ruleId\": \"e432f62b-55f6-49dd-a02f-eb24acf39d05\", \"flagConfigVersion\": 12, \"notInExperimentVariationId\": \"e432f62b-55f6-49dd-a02f-eb24acf39d05\" }}"

canReshuffleTraffic · boolean

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.

Example:

true

primarySingleMetricKey · string

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

Example:

"metric-key-123abc"

primaryFunnelKey · string

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

Example:

"metric-group-key-123abc"

randomizationUnit · string

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

Example:

"user"

reallocationFrequencyMillis · integer

The cadence (in milliseconds) to update the allocation.

Example:

3600000

covariateId · string

The ID of the covariate CSV

attributes · string[]

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

Example:

["country", "device", "os"]

Response

200

application/json

Iteration response

hypothesis · string · required

The expected outcome of this experiment

Example:

"The new button placement will increase conversion"

status · enum<string> · required

The status of the iteration: not_started, running, stopped

Available options: not_started, running, stopped

Example:

"running"

createdAt · integer<int64> · required

Timestamp of when the iteration was created

Example:

"1654104600000"

_id · string

The iteration ID

Example:

"12ab3c45de678910fgh12345"

startedAt · integer<int64>

Timestamp of when the iteration started

Example:

"1655314200000"

endedAt · integer<int64>

Timestamp of when the iteration ended

Example:

"1656610200000"

winningTreatmentId · string

The ID of the treatment chosen when the experiment stopped

Example:

"122c9f3e-da26-4321-ba68-e0fc02eced58"

winningReason · string

The reason you stopped the experiment

Example:

"We ran this iteration for two weeks and the winning variation was clear"

canReshuffleTraffic · boolean

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

Example:

true

flags · object

Details on the flag used in this experiment

Show child attributes

reallocationFrequencyMillis · integer

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

Example:

3600000

version · integer

The current version that the iteration is on

Example:

0

primaryMetric · object · deprecated

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

Show child attributes

primarySingleMetric · object

Details on the primary metric for this experiment

Show child attributes

primaryFunnel · object

Details on the primary funnel group for this experiment

Show child attributes

randomizationUnit · string

The unit of randomization for this iteration

Example:

"user"

attributes · string[]

The available attribute filters for this iteration

treatments · object[]

Details on the variations you are testing in the experiment

Show child attributes

secondaryMetrics · object[] · deprecated

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

Show child attributes

metrics · object[]

Details on the metrics for this experiment

Show child attributes

layerSnapshot · object

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

Show child attributes

covariateInfo · object

Details of the covariate file for stratified sampling

Show child attributes