---
title: "Create iteration"
method: POST
path: "/api/v2/projects/{projectKey}/environments/{environmentKey}/experiments/{experimentKey}/iterations"
tags: ["Experiments"]
---

# Create iteration

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

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

## Path parameters

- `projectKey` string, string, required — The project key
- `environmentKey` string, string, required — The environment key
- `experimentKey` string, string, required — The experiment key

## Request body

- IterationInput
  - `hypothesis` string, required — The expected outcome of this experiment
  - `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.
  - `metrics` MetricInput[], required
    - `key` string, required — The metric key
    - `isGroup` boolean — Whether this is a metric group (true) or a metric (false). Defaults to false
    - `primary` boolean — Deprecated, use <code>primarySingleMetricKey</code> and <code>primaryFunnelKey</code>. Whether this is a primary metric (true) or a secondary metric (false)
  - `primarySingleMetricKey` string — The key of the primary metric for this experiment. Either <code>primarySingleMetricKey</code> or <code>primaryFunnelKey</code> must be present.
  - `primaryFunnelKey` string — The key of the primary funnel group for this experiment. Either <code>primarySingleMetricKey</code> or <code>primaryFunnelKey</code> must be present.
  - `treatments` TreatmentInput[], required
    - `name` string, required — The treatment name
    - `baseline` boolean, required — Whether this treatment is the baseline to compare other treatments against
    - `allocationPercent` string, required — The percentage of traffic allocated to this treatment during the iteration
    - `parameters` TreatmentParameterInput[], required — Details on the flag and variation to use for this treatment
      - `flagKey` string, required — The flag key
      - `variationId` string, required — The ID of the flag variation
  - `flags` FlagsInput, required
  - `randomizationUnit` string — The unit of randomization for this iteration. Defaults to user.
  - `attributes` string[] — The attributes that this iteration's results can be sliced by

## Response `200`

Iteration response

- IterationRep
  - `_id` string — The iteration ID
  - `hypothesis` string, required — The expected outcome of this experiment
  - `status` 'not_started' | 'running' | 'stopped', required — The status of the iteration: <code>not_started</code>, <code>running</code>, <code>stopped</code>
  - `createdAt` integer, required
  - `startedAt` integer
  - `endedAt` integer
  - `winningTreatmentId` string — The ID of the treatment chosen when the experiment stopped
  - `winningReason` string — The reason you stopped the experiment
  - `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).
  - `flags` object — Details on the flag used in this experiment
  - `reallocationFrequencyMillis` integer — The cadence (in milliseconds) to update the allocation. Only present for multi-armed bandits.
  - `version` integer — The current version that the iteration is on
  - `primaryMetric` DependentMetricOrMetricGroupRep
    - `key` string, required — A unique key to reference the metric or metric group
    - `_versionId` string, required — The version ID of the metric or metric group
    - `name` string, required — A human-friendly name for the metric or metric group
    - `kind` 'pageview' | 'click' | 'custom' | 'funnel' | 'standard' | 'guardrail', required — If this is a metric, then it represents the kind of event the metric tracks. If this is a metric group, then it represents the group type
    - `isNumeric` boolean — For custom metrics, whether to track numeric changes in value against a baseline (<code>true</code>) or to track a conversion when an end user takes an action (<code>false</code>).
    - `eventKey` string — The event key sent with the metric. Only relevant for custom metrics.
    - `_links` object, required — The location and content type of related resources
    - `isGroup` boolean, required — Whether this is a metric group or a metric
    - `metrics` MetricInGroupRep[] — An ordered list of the metrics in this metric group
      - `key` string, required — The metric key
      - `_versionId` string — The version ID of the metric
      - `name` string, required — The metric name
      - `kind` 'pageview' | 'click' | 'custom', required — The kind of event the metric tracks
      - `isNumeric` boolean — For custom metrics, whether to track numeric changes in value against a baseline (<code>true</code>) or to track a conversion when an end user takes an action (<code>false</code>).
      - `unitAggregationType` 'sum' | 'average' — The type of unit aggregation to use for the metric
      - `eventKey` string — The event key sent with the metric. Only relevant for custom metrics.
      - `_links` object, required — The location and content type of related resources
      - `nameInGroup` string — Name of the metric when used within the associated metric group. Can be different from the original name of the metric. Required if and only if the metric group is a <code>funnel</code>.
      - `randomizationUnits` string[] — The randomization units for the metric
  - `primarySingleMetric` MetricV2Rep
    - `key` string, required — The metric key
    - `_versionId` string — The version ID of the metric
    - `name` string, required — The metric name
    - `kind` 'pageview' | 'click' | 'custom', required — The kind of event the metric tracks
    - `isNumeric` boolean — For custom metrics, whether to track numeric changes in value against a baseline (<code>true</code>) or to track a conversion when an end user takes an action (<code>false</code>).
    - `unitAggregationType` 'sum' | 'average' — The type of unit aggregation to use for the metric
    - `eventKey` string — The event key sent with the metric. Only relevant for custom metrics.
    - `_links` object, required — The location and content type of related resources
  - `primaryFunnel` DependentMetricGroupRepWithMetrics
    - `key` string, required — A unique key to reference the metric group
    - `name` string, required — A human-friendly name for the metric group
    - `kind` 'funnel' | 'standard' | 'guardrail', required — The type of the metric group
    - `_links` object, required — The location and content type of related resources
    - `metrics` MetricInGroupRep[] — The metrics in the metric group
      - `key` string, required — The metric key
      - `_versionId` string — The version ID of the metric
      - `name` string, required — The metric name
      - `kind` 'pageview' | 'click' | 'custom', required — The kind of event the metric tracks
      - `isNumeric` boolean — For custom metrics, whether to track numeric changes in value against a baseline (<code>true</code>) or to track a conversion when an end user takes an action (<code>false</code>).
      - `unitAggregationType` 'sum' | 'average' — The type of unit aggregation to use for the metric
      - `eventKey` string — The event key sent with the metric. Only relevant for custom metrics.
      - `_links` object, required — The location and content type of related resources
      - `nameInGroup` string — Name of the metric when used within the associated metric group. Can be different from the original name of the metric. Required if and only if the metric group is a <code>funnel</code>.
      - `randomizationUnits` string[] — The randomization units for the metric
  - `randomizationUnit` string — The unit of randomization for this iteration
  - `attributes` string[] — The available attribute filters for this iteration
  - `treatments` TreatmentRep[] — Details on the variations you are testing in the experiment
    - `_id` string — The treatment ID. This is the variation ID from the flag.
    - `name` string, required — The treatment name. This is the variation name from the flag.
    - `allocationPercent` string, required — The percentage of traffic allocated to this treatment during the iteration
    - `baseline` boolean — Whether this treatment is the baseline to compare other treatments against
    - `parameters` ParameterRep[] — Details on the flag and variation used for this treatment
      - `variationId` string
      - `flagKey` string
  - `secondaryMetrics` MetricV2Rep[] — Deprecated, use <code>metrics</code> instead. Details on the secondary metrics for this experiment.
    - `key` string, required — The metric key
    - `_versionId` string — The version ID of the metric
    - `name` string, required — The metric name
    - `kind` 'pageview' | 'click' | 'custom', required — The kind of event the metric tracks
    - `isNumeric` boolean — For custom metrics, whether to track numeric changes in value against a baseline (<code>true</code>) or to track a conversion when an end user takes an action (<code>false</code>).
    - `unitAggregationType` 'sum' | 'average' — The type of unit aggregation to use for the metric
    - `eventKey` string — The event key sent with the metric. Only relevant for custom metrics.
    - `_links` object, required — The location and content type of related resources
  - `metrics` DependentMetricOrMetricGroupRep[] — Details on the metrics for this experiment
    - `key` string, required — A unique key to reference the metric or metric group
    - `_versionId` string, required — The version ID of the metric or metric group
    - `name` string, required — A human-friendly name for the metric or metric group
    - `kind` 'pageview' | 'click' | 'custom' | 'funnel' | 'standard' | 'guardrail', required — If this is a metric, then it represents the kind of event the metric tracks. If this is a metric group, then it represents the group type
    - `isNumeric` boolean — For custom metrics, whether to track numeric changes in value against a baseline (<code>true</code>) or to track a conversion when an end user takes an action (<code>false</code>).
    - `eventKey` string — The event key sent with the metric. Only relevant for custom metrics.
    - `_links` object, required — The location and content type of related resources
    - `isGroup` boolean, required — Whether this is a metric group or a metric
    - `metrics` MetricInGroupRep[] — An ordered list of the metrics in this metric group
      - `key` string, required — The metric key
      - `_versionId` string — The version ID of the metric
      - `name` string, required — The metric name
      - `kind` 'pageview' | 'click' | 'custom', required — The kind of event the metric tracks
      - `isNumeric` boolean — For custom metrics, whether to track numeric changes in value against a baseline (<code>true</code>) or to track a conversion when an end user takes an action (<code>false</code>).
      - `unitAggregationType` 'sum' | 'average' — The type of unit aggregation to use for the metric
      - `eventKey` string — The event key sent with the metric. Only relevant for custom metrics.
      - `_links` object, required — The location and content type of related resources
      - `nameInGroup` string — Name of the metric when used within the associated metric group. Can be different from the original name of the metric. Required if and only if the metric group is a <code>funnel</code>.
      - `randomizationUnits` string[] — The randomization units for the metric
  - `layerSnapshot` LayerSnapshotRep
    - `key` string, required — Key of the layer the experiment was part of
    - `name` string, required — Layer name at the time this experiment iteration was stopped
    - `reservationPercent` integer, required — Percent of layer traffic that was reserved in the layer for this experiment iteration
    - `otherReservationPercent` integer, required — Percent of layer traffic that was reserved for other experiments in the same environment, when this experiment iteration was stopped

## Other responses

- `400` — Invalid request
- `401` — Invalid access token
- `403` — Forbidden
- `404` — Invalid resource identifier
- `429` — Rate limited

## Changes

- **2026-02-28** `69c5c9aafe78` — 3 warning, 9 info
  - added the new `not_started` enum value to the `status` response property for the response status `200`
  - added the new `running` enum value to the `status` response property for the response status `200`
  - added the new `stopped` enum value to the `status` response property for the response status `200`
  - added the optional property `metrics/items/eventKey` to the response with the `200` status
  - …8 more
- **2025-07-08** `b2724c5174d1` — 3 warning
  - added the new `guardrail` enum value to the `metrics/items/kind` response property for the response status `200`
  - added the new `guardrail` enum value to the `primaryFunnel/kind` response property for the response status `200`
  - added the new `guardrail` enum value to the `primaryMetric/kind` response property for the response status `200`

[Change history](https://skmtc.dev/launchdarkly/apis/launchdarkly-rest-api/changes/api/v2/projects/:projectKey/environments/:environmentKey/experiments/:experimentKey/iterations/post.md)

---

[API](https://skmtc.dev/launchdarkly/apis/launchdarkly-rest-api.md) · [All operations](https://skmtc.dev/launchdarkly/apis/launchdarkly-rest-api/llms.txt) · [OpenAPI document](https://skmtc-service-production.skmtc.workers.dev/v1/apis/launchdarkly/launchdarkly-rest-api/revisions/69c5c9aafe78/schema)