Patch experiment

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

Update an experiment. Updating an experiment uses the semantic patch format.

To make a semantic patch request, you must append domain-model=launchdarkly.semanticpatch to your Content-Type header. To learn more, read Updates using semantic patch.

Instructions

Semantic patch requests support the following kind instructions for updating experiments.

updateName

Updates the experiment name.

Parameters

• value: The new name.

Here’s an example:

{
  "instructions": [{
    "kind": "updateName",
    "value": "Example updated experiment name"
  }]
}

updateDescription

Updates the experiment description.

Parameters

• value: The new description.

Here’s an example:

{
  "instructions": [{
    "kind": "updateDescription",
    "value": "Example updated description"
  }]
}

startIteration

Starts a new iteration for this experiment. You must create a new iteration before calling this instruction.

An iteration may not be started until it meets the following criteria:

• Its associated flag is toggled on and is not archived
• Its randomizationUnit is set
• At least one of its treatments has a non-zero allocationPercent

Parameters

• changeJustification: The reason for starting a new iteration. Required when you call startIteration on an already running experiment, otherwise optional.

Here’s an example:

{
  "instructions": [{
    "kind": "startIteration",
    "changeJustification": "It's time to start a new iteration"
  }]
}

stopIteration

Stops the current iteration for this experiment.

Parameters

• winningTreatmentId: The ID of the winning treatment. Treatment IDs are returned as part of the Get experiment response. They are the _id of each element in the treatments array.
• winningReason: The reason for the winner

Here’s an example:

{
  "instructions": [{
    "kind": "stopIteration",
    "winningTreatmentId": "3a548ec2-72ac-4e59-8518-5c24f5609ccf",
    "winningReason": "Example reason to stop the iteration"
  }]
}

archiveExperiment

Archives this experiment. Archived experiments are hidden by default in the LaunchDarkly user interface. You cannot start new iterations for archived experiments.

Here’s an example:

{
  "instructions": [{ "kind": "archiveExperiment" }]
}

restoreExperiment

Restores an archived experiment. After restoring an experiment, you can start new iterations for it again.

Here’s an example:

{
  "instructions": [{ "kind": "restoreExperiment" }]
}

PATCH /api/v2/projects/{projectKey}/environments/{environmentKey}/experiments/{experimentKey}

Patch experiment

cURL

curl --request PATCH \
  --url https://app.launchdarkly.com/api/v2/projects/{projectKey}/environments/{environmentKey}/experiments/{experimentKey} \
  --header 'Authorization: <api-key>' \
  --header 'Content-Type: application/json' \
  --data '
{
  "comment": "Example comment describing the update",
  "instructions": [
    {
      "kind": "updateName",
      "value": "Updated experiment name"
    }
  ]
}
'

200

{
  "key": "experiment-key-123abc",
  "name": "Example experiment",
  "_maintainerId": "12ab3c45de678910fgh12345",
  "_creationDate": "1654104600000",
  "environmentKey": "<string>",
  "_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"
    }
  },
  "_id": "12ab3c45de678910fgh12345",
  "description": "An example experiment, used in testing",
  "methodology": "bayesian",
  "dataSource": "snowflake",
  "archivedDate": "1654104600000",
  "tags": [
    "experiment",
    "feature"
  ],
  "holdoutId": "f3b74309-d581-44e1-8a2b-bb2933b4fe40",
  "currentIteration": {
    "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"
    }
  },
  "type": "experiment",
  "draftIteration": {
    "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"
    }
  },
  "previousIterations": [
    {
      "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"
      }
    }
  ],
  "analysisConfig": {
    "bayesianThreshold": "<string>",
    "significanceThreshold": "<string>",
    "testDirection": "<string>",
    "multipleComparisonCorrectionMethod": "bonferroni",
    "multipleComparisonCorrectionScope": "variations",
    "sequentialTestingEnabled": true
  }
}

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

instructions · object[] · required

The instructions to perform when updating. This should be an array with objects that look like {"kind": "update_action"}. Some instructions also require a value field in the array element.

Show child attributes

Example:

"[{\"kind\": \"updateName\", \"value\": \"Updated experiment name\"}]"

comment · string

Optional comment describing the update

Example:

"Optional comment"

Response

200

application/json

Experiment response

key · string · required

The experiment key

Example:

"experiment-key-123abc"

name · string · required

The experiment name

Example:

"Example experiment"

_maintainerId · string · required

The ID of the member who maintains this experiment.

Example:

"12ab3c45de678910fgh12345"

_creationDate · integer<int64> · required

Timestamp of when the experiment was created

Example:

"1654104600000"

environmentKey · string · required

_links · object · required

The location and content type of related resources

Show child attributes

Example:

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

_id · string

The experiment ID

Example:

"12ab3c45de678910fgh12345"

description · string

The experiment description

Example:

"An example experiment, used in testing"

methodology · enum<string>

The results analysis approach.

Available options: bayesian, frequentist, export_only

Example:

"bayesian"

dataSource · enum<string>

The source of metric data in order to analyze results. Defaults to "launchdarkly" when not provided.

Available options: launchdarkly, snowflake

Example:

"snowflake"

archivedDate · integer<int64>

Timestamp of when the experiment was archived

Example:

"1654104600000"

tags · string[]

Tags for the experiment

Example:

["experiment", "feature"]

holdoutId · string

The holdout ID

Example:

"f3b74309-d581-44e1-8a2b-bb2933b4fe40"

currentIteration · object

Details on the current iteration

Show child attributes

type · string

The experiment type

Example:

"experiment"

draftIteration · object

Details on the current iteration. This iteration may be already started, or may still be a draft.

Show child attributes

previousIterations · object[]

Details on the previous iterations for this experiment.

Show child attributes

analysisConfig · object

Details of the Analysis Configuration for this experiment.

Show child attributes