Experiments (beta)

This feature is in beta

To use this feature, pass in a header including the LD-API-Version key with value set to beta. Use this header with each call. To learn more, read Beta resources.

An experiment is a running tally of user behaviors based on which variation of a feature flag they receive. In LaunchDarkly, an experiment requires two things: a metric that defines what user behaviors to track, and at least one flag associated with that metric.

Experiments are largely managed via PATCH requests to the Flags API. There are also dedicated API resources for getting and deleting experiment data.

Adding an experiment

To add an experiment to a flag, add a new object to the /experiments/items/ property.

The object must contain:

  1. The key of the metric you want to use for the experiment.
  2. (Optional) A list of keys for the environments where the experiment should record data.
PATCH /api/v2/flags/{projKey}/{flagKey}
[
    {
        "op": "add",
        "path": "/experiments/items/0",
        "value": {
            "metricKey": "example-metric",
            "environments": []
        }
    }
]

Removing an experiment

To remove an experiment, remove the corresponding item from the experiments or items property.

PATCH /api/v2/flags/{projKey}/{flagKey}
[
    {
        "op": "remove",
        "path": "/experiments/items/0"
    }
]

Starting or resuming an experiment

To start recording data for an experiment in an environment, add the environment key to the list of environments for that experiment.

PATCH /api/v2/flags/{projKey}/{flagKey}
[
    {
        "op": "add",
        "path": "/experiments/items/0/environments/0",
        "value": "production"
    }
]

Pausing an experiment

To pause collecting data for an experiment in a specific environment, remove the environment from the list that experiment uses.

PATCH /api/v2/flags/{projKey}/{flagKey}
[
  {
    "op": "remove",
    "path": "/experiments/items/0/environments/0"
  }
]

Updating the baseline

To update the baseline for all experiments on a flag across all environments in the project, replace the baselineIdx property with the index of the new baseline variation.

PATCH /api/v2/flags/{projKey}/{flagKey}
[
  {
    "op": "replace",
    "path": "/experiments/baselineIdx",
    "value": 1
  }
]

Get experiment results

Get detailed experiment result data

Request
Security:
ApiKey (readwrite)
path Parameters
projKey
required
string <string>

The project key

flagKey
required
string <string>

The flag key

envKey
required
string <string>

The environment key

metricKey
required
string <string>

The metric key

query Parameters
from
integer <int64>

A timestamp denoting the start of the data collection period, expressed as a Unix epoch time in milliseconds.

to
integer <int64>

A timestamp denoting the end of the data collection period, expressed as a Unix epoch time in milliseconds.

Responses
200

Experiment results response

400

Invalid request

401

Invalid access token

403

Forbidden

404

Invalid resource identifier

429

Rate limited

get/api/v2/flags/{projKey}/{flagKey}/experiments/{envKey}/{metricKey}
Request samples
curl -i -X GET \
  https://app.launchdarkly.com/api/v2/flags/:projKey/:flagKey/experiments/:envKey/:metricKey \
  -H 'Authorization: YOUR_API_KEY_HERE'
Response samples
application/json
{
  • "_links": {
    },
  • "metadata": [
    ],
  • "totals": [
    ],
  • "series": [
    ],
  • "stats": {
    },
  • "granularity": "string",
  • "metricSeen": {
    }
}

Reset experiment results

Reset all experiment results by deleting all existing data for an experiment

Request
Security:
ApiKey (readwrite)
path Parameters
projKey
required
string <string>

The project key

flagKey
required
string <string>

The feature flag's key

envKey
required
string <string>

The environment key

metricKey
required
string <string>

The metric's key

Responses
204

Experiment results reset successfully

401

Invalid access token

403

Forbidden

404

Invalid resource identifier

429

Rate limited

delete/api/v2/flags/{projKey}/{flagKey}/experiments/{envKey}/{metricKey}/results
Request samples
curl -i -X DELETE \
  https://app.launchdarkly.com/api/v2/flags/:projKey/:flagKey/experiments/:envKey/:metricKey/results \
  -H 'Authorization: YOUR_API_KEY_HERE'
Response samples
application/json
{
  • "code": "unauthorized",
  • "message": "invalid key"
}