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

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

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.

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

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

createdAtlong

Timestamp of when the iteration was created

_idstringOptional

The iteration ID

startedAtlongOptional

Timestamp of when the iteration started

endedAtlongOptional

Timestamp of when the iteration ended

winningTreatmentIdstringOptional

The ID of the treatment chosen when the experiment stopped

winningReasonstringOptional

The reason you stopped the experiment

canReshuffleTrafficbooleanOptional

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 objectsOptional

Details on the flag used in this experiment

reallocationFrequencyMillisintegerOptional

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

versionintegerOptional

The current version that the iteration is on

primaryMetricobjectOptional

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

primarySingleMetricobjectOptional

Details on the primary metric for this experiment

primaryFunnelobjectOptional

Details on the primary funnel group for this experiment

randomizationUnitstringOptional

The unit of randomization for this iteration

attributeslist of stringsOptional

The available attribute filters for this iteration

treatmentslist of objectsOptional

Details on the variations you are testing in the experiment

metricslist of objectsOptional

Details on the metrics for this experiment

layerSnapshotobjectOptional

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

covariateInfoobjectOptional

Details of the covariate file for stratified sampling

secondaryMetricslist of objectsOptionalDeprecated

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