v5

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

Experiments

Create experiment

Create an experiment.

To run this experiment, you'll need to create an iteration and then update the experiment with the startIteration instruction.

To learn more, read Creating experiments.

post/api/v2/projects/{projectKey}/environments/{environmentKey}/experiments

Path parameters

projectKeystring string required

The project key

environmentKeystring string required

The environment key

Request body

namestring required

The experiment name

descriptionstring

The experiment description

maintainerIdstring

The ID of the member who maintains this experiment

keystring required

The experiment key

holdoutIdstring

The ID of the holdout

tagsstring[]

Tags for the experiment

Example request

{
  "name": "Example experiment",
  "description": "An example experiment, used in testing",
  "maintainerId": "12ab3c45de678910fgh12345",
  "key": "experiment-key-123abc",
  "iteration": {
    "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"
    ]
  },
  "holdoutId": "f3b74309-d581-44e1-8a2b-bb2933b4fe40"
}

Response

Experiment response

_idstring

The experiment ID

keystring required

The experiment key

namestring required

The experiment name

descriptionstring

The experiment description

_maintainerIdstring required

The ID of the member who maintains this experiment.

_creationDateinteger required

environmentKeystring required

archivedDateinteger

tagsstring[]

Tags for the experiment

_linksobject required

The location and content type of related resources

holdoutIdstring

The holdout ID

Example response

{
  "_id": "12ab3c45de678910fgh12345",
  "key": "experiment-key-123abc",
  "name": "Example experiment",
  "description": "An example experiment, used in testing",
  "_maintainerId": "12ab3c45de678910fgh12345",
  "tags": [
    "experiment",
    "feature"
  ],
  "_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"
    }
  },
  "holdoutId": "f3b74309-d581-44e1-8a2b-bb2933b4fe40",
  "currentIteration": {
    "_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
    }
  },
  "draftIteration": {
    "_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
    }
  },
  "previousIterations": [
    {
      "_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
      }
    }
  ]
}