v5

latestOpenAPI 3.0.3Apache 2.0raw.githubusercontent.com2026-02-283466592.5 MB

Experiments

Create iteration

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

Path parameters

projectKeystring string required

The project key

environmentKeystring string required

The environment key

experimentKeystring string required

The experiment key

Request body

hypothesisstring required

The expected outcome of this experiment

canReshuffleTrafficboolean

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.

primarySingleMetricKeystring

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

primaryFunnelKeystring

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

flagsFlagsInput required

randomizationUnitstring

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

attributesstring[]

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

Example request

{
  "hypothesis": "Example hypothesis, the new button placement will increase conversion",
  "canReshuffleTraffic": true,
  "metrics": [
    {
      "key": "metric-key-123abc",
      "isGroup": true,
      "primary": true
    }
  ],
  "primarySingleMetricKey": "metric-key-123abc",
  "primaryFunnelKey": "metric-group-key-123abc",
  "treatments": [
    {
      "name": "Treatment 1",
      "baseline": true,
      "allocationPercent": "10",
      "parameters": [
        {
          "flagKey": "example-flag-for-experiment",
          "variationId": "e432f62b-55f6-49dd-a02f-eb24acf39d05"
        }
      ]
    }
  ],
  "randomizationUnit": "user",
  "attributes": [
    "country",
    "device",
    "os"
  ]
}

Response

Iteration response

_idstring

The iteration ID

hypothesisstring 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>

createdAtinteger required

startedAtinteger

endedAtinteger

winningTreatmentIdstring

The ID of the treatment chosen when the experiment stopped

winningReasonstring

The reason you stopped the experiment

canReshuffleTrafficboolean

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

flagsobject

Details on the flag used in this experiment

reallocationFrequencyMillisinteger

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

versioninteger

The current version that the iteration is on

randomizationUnitstring

The unit of randomization for this iteration

attributesstring[]

The available attribute filters for this iteration

Example response

{
  "_id": "12ab3c45de678910fgh12345",
  "hypothesis": "The new button placement will increase conversion",
  "status": "running",
  "winningTreatmentId": "122c9f3e-da26-4321-ba68-e0fc02eced58",
  "winningReason": "We ran this iteration for two weeks and the winning variation was clear",
  "canReshuffleTraffic": true,
  "reallocationFrequencyMillis": 3600000,
  "primaryMetric": {
    "key": "metric-key-123abc",
    "name": "My metric",
    "kind": "custom",
    "isNumeric": true,
    "eventKey": "event-key-123abc",
    "_links": {
      "self": {
        "href": "/api/v2/metrics/my-project/my-metric",
        "type": "application/json"
      }
    },
    "metrics": [
      {
        "key": "metric-key-123abc",
        "_versionId": "version-id-123abc",
        "name": "Example metric",
        "kind": "custom",
        "isNumeric": true,
        "unitAggregationType": "sum",
        "eventKey": "event-key-123abc",
        "_links": {
          "self": {
            "href": "/api/v2/metrics/my-project/my-metric",
            "type": "application/json"
          }
        },
        "nameInGroup": "Step 1",
        "randomizationUnits": [
          "user"
        ]
      }
    ]
  },
  "primarySingleMetric": {
    "key": "metric-key-123abc",
    "_versionId": "version-id-123abc",
    "name": "Example metric",
    "kind": "custom",
    "isNumeric": true,
    "unitAggregationType": "sum",
    "eventKey": "event-key-123abc",
    "_links": {
      "self": {
        "href": "/api/v2/metrics/my-project/my-metric",
        "type": "application/json"
      }
    }
  },
  "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",
        "_versionId": "version-id-123abc",
        "name": "Example metric",
        "kind": "custom",
        "isNumeric": true,
        "unitAggregationType": "sum",
        "eventKey": "event-key-123abc",
        "_links": {
          "self": {
            "href": "/api/v2/metrics/my-project/my-metric",
            "type": "application/json"
          }
        },
        "nameInGroup": "Step 1",
        "randomizationUnits": [
          "user"
        ]
      }
    ]
  },
  "randomizationUnit": "user",
  "treatments": [
    {
      "_id": "122c9f3e-da26-4321-ba68-e0fc02eced58",
      "name": "Treatment 1",
      "allocationPercent": "10",
      "baseline": true
    }
  ],
  "secondaryMetrics": [
    {
      "key": "metric-key-123abc",
      "_versionId": "version-id-123abc",
      "name": "Example metric",
      "kind": "custom",
      "isNumeric": true,
      "unitAggregationType": "sum",
      "eventKey": "event-key-123abc",
      "_links": {
        "self": {
          "href": "/api/v2/metrics/my-project/my-metric",
          "type": "application/json"
        }
      }
    }
  ],
  "metrics": [
    {
      "key": "metric-key-123abc",
      "name": "My metric",
      "kind": "custom",
      "isNumeric": true,
      "eventKey": "event-key-123abc",
      "_links": {
        "self": {
          "href": "/api/v2/metrics/my-project/my-metric",
          "type": "application/json"
        }
      },
      "metrics": [
        {
          "key": "metric-key-123abc",
          "_versionId": "version-id-123abc",
          "name": "Example metric",
          "kind": "custom",
          "isNumeric": true,
          "unitAggregationType": "sum",
          "eventKey": "event-key-123abc",
          "_links": {
            "self": {
              "href": "/api/v2/metrics/my-project/my-metric",
              "type": "application/json"
            }
          },
          "nameInGroup": "Step 1",
          "randomizationUnits": [
            "user"
          ]
        }
      ]
    }
  ],
  "layerSnapshot": {
    "key": "checkout-flow",
    "name": "Checkout Flow",
    "reservationPercent": 10,
    "otherReservationPercent": 70
  }
}