# Experiment Management API Experiment Endpoints

> For AI agents: a documentation index is available at [/docs/llms.txt](/docs/llms.txt). Append `.md` to any page URL for markdown, or send `Accept: text/markdown`.

| Name | Description |
| --- | --- |
| [List](#list) | List of experiments including their configuration details. |
| [Get details](#get-details) | Get the configuration details of an experiment. |
| [List versions](#list-versions) | List all versions for an experiment. |
| [Get version details](#get-version-details) | Get a specific version for an experiment. |
| [List variants](#list-variants) | List all variants for an experiment. |
| [Get variant details](#get-variant-details) | Get a specific variant for an experiment. |
| [Get variant inclusions](#get-variant-inclusions) | Get all inclusions (users) for a variant. |
| [Get variant cohort inclusions](#get-variant-cohort-inclusions) | Get all cohort inclusions for a variant. |
| [Create variant](#create-variant) | Create a new variant for an experiment. |
| [Edit variant](#edit-variant) | Edit a variant for an experiment. |
| [Remove variant](#remove-variant) | Remove a variant from an experiment. |
| [Add users to variant](#add-users-to-variant) | Add users to experiment's variant. |
| [Add cohorts to variant](#add-cohorts-to-variant) | Add cohorts to experiment's variant. |
| [Remove users from variant](#remove-users-from-variant) | Remove users from experiment's variant. |
| [Remove all users from variant](#remove-all-users-from-variant) | Remove all users from experiment's variant. |
| [Bulk remove users from variant](#bulk-remove-users-from-variant) | Bulk remove users from experiment's variant. |
| [Bulk remove cohorts from variant](#bulk-remove-cohorts-from-variant) | Bulk remove cohorts from experiment's variant. |
| [List deployments](#list-deployments) | List all deployments for an experiment. |
| [Add deployment](#create-deployment) | Add a deployment to an experiment. |
| [Remove deployment](#remove-deployment) | Remove a deployment from an experiment. |
| [Edit](#edit) | Edit experiment. |
| [Create](#create) | Create a new experiment. |

> **Note:** EU data residency
>
> The examples on this page use the default base URL `https://experiment.amplitude.com`. If your project uses Amplitude's EU data center, use `https://experiment.eu.amplitude.com` instead. For more information, refer to [Regions](https://amplitude.com/docs/apis/experiment/experiment-management-api#regions).

## List

```bash
GET https://experiment.amplitude.com/api/1/experiments
```

Fetch a list of experiments and their configuration details. Results are ordered with the most recently created items first.

> **Note:**
>
> The list includes only feature and web experiments, and the `deliveryMethod` field identifies each experiment's type. Earlier versions of this endpoint could return experiments with other delivery methods, such as nudge experiments, with no way to distinguish them.

### Query parameters

| Name | Description |
| --- | --- |
| `key` | Filter experiments whose experiment key matches this value. |
| `projectId` | Filter experiments that belong to this project. |
| `limit` | The maximum number of experiments to return. Capped at 1000. |
| `cursor` | The offset to start the "page" of results from. |
| `includeArchived` | Optional. Boolean. Default is false. When false, return only active experiments. When true, return active and archived experiments. |
| `deliveryMethod` | Optional. String. Filter experiments by delivery method: `feature` or `web`. When omitted, return both feature and web experiments. |

### Response

A successful request returns a `200 OK` response and a list of experiments encoded as JSON in the response body. `createdAt` and `lastModifiedAt` are in UTC in ISO 8601 format. `deliveryMethod` is `feature` for feature experiments or `web` for web experiments.

#### Request

```bash
curl --request GET \
--url 'https://experiment.amplitude.com/api/1/experiments?limit=1000' \
--header 'Accept: application/json' \
--header 'Authorization: Bearer <management-api-key>'
```

#### Response

```json
{
    "experiments": [
        {
            "id": <id>,
            "projectId": <projectId>,
            "deployments": [<deploymentId>],
            "key": "experiment-key",
            "name": "experiment-name",
            "decision": null,
            "decisionReason": null,
            "description": "description",
            "enabled": true,
            "evaluationMode": "remote",
            "bucketingKey": "amplitude_id",
            "bucketingSalt": <bucketingSalt>,
            "bucketingUnit": "User",
            "variants": [
                {
                    "key": "control"
                },
                {
                    "key": "treatment"
                }
            ],
            "rolledOutVariant": null,
            "rolloutPercentage": 10,
            "rolloutWeights": {
                "control": 1,
                "treatment": 1
            },
            "targetSegments": [
                {
                    "name": "Segment 1",
                    "conditions": [
                        {
                            "prop": "device_id",
                            "op": "is",
                            "type": "property",
                            "values": [
                                "(none)"
                            ]
                        }
                    ],
                    "percentage": 50,
                    "bucketingKey": "amplitude_id",
                    "rolloutWeights": {
                        "control": 1,
                        "treatment": 1
                    }
                }
            ],
            "parentDependencies": {
                "flags": {
                    "12345": [
                        "slot-1"
                    ]
                },
                "operator": "all"
            },
            "stickyBucketing": false,
            "state": "planning",
            "startDate": null,
            "endDate": null,
            "experimentType": "a-b-test",
            "deliveryMethod": "feature",
            "createdBy": "abc@amplitude.com",
            "lastModifiedBy": "abc@amplitude.com",
            "createdAt":"2022-09-09T15:29:47.940Z",
            "lastModifiedAt":"2023-01-25T11:43:41.073Z"
        },
        "nextCursor": <cursorId>
    ]
}
```

## Get details

```bash
GET https://experiment.amplitude.com/api/1/experiments/<id>
```

Fetch the configuration details of an experiment.

### Path variables

| Name | Description |
| --- | --- |
| `id` | Required. String. The experiment's ID. Find the ID in the URL of the experiment in the Amplitude app. |

### Response

A successful request returns a `200 OK` response and a JSON object with the experiment's details.

#### Request

```bash
curl --request GET \
    --url 'https://experiment.amplitude.com/api/1/experiments/<id>' \
    --header 'Accept: application/json' \
    --header 'Authorization: Bearer <management-api-key>'
```

#### Response

```bash
{
    "id": <id>,
    "projectId": <projectId>,
    "deployments": [<deploymentId>],
    "key": "experiment-key",
    "name": "experiment-key",
    "decision": null,
    "decisionReason": null,
    "description": "save button color",
    "enabled": true,
    "evaluationMode": "remote",
    "bucketingKey": "amplitude_id",
    "bucketingSalt": <bucketingSalt>,
    "bucketingUnit": "User",
    "variants": [
        {
            "key": "control"
        },
        {
            "key": "treatment"
        }
    ],
    "rolledOutVariant": null,
    "rolloutPercentage": 0,
    "rolloutWeights": {
        "control": 1,
        "treatment": 1
    },
    "targetSegments": [
        {
            "name": "Segment 1",
            "conditions": [
                {
                    "prop": "city",
                    "op": "is",
                    "type": "property",
                    "values": [
                        "San Francisco"
                    ]
                }
            ],
            "percentage": 0,
            "bucketingKey": "amplitude_id",
            "rolloutWeights": {
                "control": 1,
                "treatment": 1
            }
        }
    ],
    "parentDependencies": {
        "flags": {
            "12345": [
                "slot-1"
            ]
        },
        "operator": "all"
    },
    "stickyBucketing": false,
    "state": "running",
    "startDate": "2023-07-29",
    "endDate": null,
    "experimentType": "a-b-test",
    "deliveryMethod": "feature",
    "deleted": false,
    "tags": [],
    "createdBy": "x@amplitude.com"
}
```

## List versions

```bash
GET https://experiment.amplitude.com/api/1/experiments/{id}/versions
```

Fetch a list of all versions for an experiment.

### Path variables

| Name | Description |
| --- | --- |
| `id` | Required. Type: `string`. The experiment's ID. Find the ID in the URL of the experiment in the Amplitude app. |

### Response

A successful request returns a `200 OK` response and a list of the experiment's versions encoded as an array of JSON objects in the response body. Versions are sorted in descending order.

#### Request

```bash
curl --request GET \
    --url 'https://experiment.amplitude.com/api/1/experiments/<id>/versions' \
    --header 'Accept: application/json' \
    --header 'Authorization: Bearer <management-api-key>'
```

#### Response

```json
[
    {
        "createdAt": "2023-07-29T03:30:18.427Z",
        "createdBy": <userId>,
        "version": 3,
        "flagConfig": {
            "id": <id>,
            "projectId": <projectId>,
            "deployments": [<deploymentId>],
            "key": "experiment-key",
            "name": "experiment-key",
            "description": "save button color",
            "enabled": true,
            "bucketingKey": "amplitude_id",
            "variants": [
                {
                    "key": "control"
                },
                {
                    "key": "treatment"
                }
            ],
            "rolloutWeights": {
                "control": 1,
                "treatment": 1
            },
            "targetSegments": [
                {
                    "name": "Segment 1",
                    "conditions": [
                        {
                            "prop": "city",
                            "op": "is",
                            "type": "property",
                            "values": [
                                "San Francisco"
                            ]
                        }
                    ],
                    "percentage": 0,
                    "bucketingKey": "amplitude_id",
                    "rolloutWeights": {
                        "control": 1,
                        "treatment": 1
                    }
                }
            ],
            "stickyBucketing": false,
            "startDate": "2023-07-29",
            "endDate": "2023-07-29",
            "experimentType": "a-b-test"
        }
    },
    {
        "createdAt": "2023-07-29T03:26:23.603Z",
        "createdBy": <userId>,
        "version": 2,
        "flagConfig": {
            "id": <id>,
            "projectId": <projectId>,
            "deployments": [],
            "key": "experiment-key",
            "name": "experiment-key",
            "description": "save button color",
            "enabled": false,
            "bucketingKey": "amplitude_id",
            "variants": [
                {
                    "key": "control"
                },
                {
                    "key": "treatment"
                }
            ],
            "rolloutWeights": {
                "control": 1,
                "treatment": 1
            },
            "targetSegments": [],
            "stickyBucketing": false,
            "startDate": null,
            "endDate": null,
            "experimentType": "a-b-test"
        }
    },
    {
        "createdAt": "2023-07-29T03:25:42.236Z",
        "createdBy": <userId>,
        "version": 1,
        "flagConfig": {
            "id": <id>,
            "projectId": <projectId>,
            "deployments": [],
            "key": "experiment-key",
            "name": "experiment-key",
            "description": "",
            "enabled": false,
            "bucketingKey": "amplitude_id",
            "variants": [
                {
                    "key": "control"
                },
                {
                    "key": "treatment"
                }
            ],
            "rolloutWeights": {
                "control": 1,
                "treatment": 1
            },
            "targetSegments": [],
            "stickyBucketing": false,
            "startDate": null,
            "endDate": null,
            "experimentType": "a-b-test"
        }
    }
]
```

## Get version details

```bash
GET https://experiment.amplitude.com/api/1/experiments/{id}/versions/{versionId}
```

Fetch details of a specific version of an experiment.

### Path variables

| Name | Description |
| --- | --- |
| `id` | Required. Type: `string`. The experiment's ID. Find the ID in the URL of the experiment in the Amplitude app. |
| `versionId` | Required. Type: `string`. The version's ID. |

### Response

A successful request returns a `200 OK` response and a JSON object with details of the version.

#### Request

```curl
curl --request GET \
    --url 'https://experiment.amplitude.com/api/1/experiments/<id>/versions/<versionId>' \
    --header 'Accept: application/json' \
    --header 'Authorization: Bearer <management-api-key>'
```

#### Response

```json
{
    "createdAt": "2023-07-29T03:30:18.427Z",
    "createdBy": <userId>,
    "version": 3,
    "flagConfig": {
        "id": <id>,
        "projectId": <projectId>,
        "deployments": [<deploymentId>],
        "key": "experiment-key",
        "name": "experiment-key",
        "description": "save button color",
        "enabled": true,
        "bucketingKey": "amplitude_id",
        "variants": [
            {
                "key": "control"
            },
            {
                "key": "treatment"
            }
        ],
        "rolloutWeights": {
            "control": 1,
            "treatment": 1
        },
        "targetSegments": [
            {
                "name": "Segment 1",
                "conditions": [
                    {
                        "prop": "city",
                        "op": "is",
                        "type": "property",
                        "values": [
                            "San Francisco"
                        ]
                    }
                ],
                "percentage": 0,
                "bucketingKey": "amplitude_id",
                "rolloutWeights": {
                    "control": 1,
                    "treatment": 1
                }
            }
        ],
        "stickyBucketing": false,
        "startDate": "2023-07-29",
        "endDate": "2023-07-29",
        "experimentType": "a-b-test"
    }
}
```

## List variants

```bash
GET https://experiment.amplitude.com/api/1/experiments/{id}/variants
```

Fetch a list of all variants for an experiment.

### Path variables

| Name | Description |
| --- | --- |
| `id` | Required. Type: `string`. The experiment's ID. Find the ID in the URL of the experiment in the Amplitude app. |

### Response

A successful request returns a `200 OK` response and a list of variants encoded as an array of JSON objects in the response body.

#### Request

```bash
curl --request GET \
    --url 'https://experiment.amplitude.com/api/1/experiments/<id>/variants' \
    --header 'Accept: application/json' \
    --header 'Authorization: Bearer <management-api-key>'
```

#### Response

```json
[
  {
    "key": "control",
    "name": "",
    "payload": {},
    "description": "",
    "rolloutWeight": 1
  },
  {
    "key": "treatment",
    "name": "",
    "payload": {},
    "description": "",
    "rolloutWeight": 1
  }
]
```

## Get variant details

```bash
GET https://experiment.amplitude.com/api/1/experiments/{id}/variants/{variantKey}
```

Fetch details of a specific variant of an experiment.

### Path variables

| Name | Description |
| --- | --- |
| `id` | Required. Type: `string`. The experiment's ID. Find the ID in the URL of the experiment in the Amplitude app. |
| `variantKey` | Required. Type: `string`. The variant's key. |

### Response

A successful request returns a `200 OK` response and a JSON object with details of the experiment variant.

#### Request

```bash
curl --request GET \
    --url 'https://experiment.amplitude.com/api/1/experiments/<id>/variants/<variantKey>' \
    --header 'Accept: application/json' \
    --header 'Authorization: Bearer <management-api-key>'
```

#### Response

```bash
{
    "key": "control",
    "name": "",
    "payload": {},
    "description": "",
    "rolloutWeight": 1
}
```

## Get variant inclusions

```bash
GET https://experiment.amplitude.com/api/1/experiments/{id}/variants/{variantKey}/users
```

Fetch a list of inclusions for a specific variant of an experiment.

### Path variables

| Name | Description |
| --- | --- |
| `id` | Required. Type: `string`. The experiment's ID. Find the ID in the URL of the experiment in the Amplitude app. |
| `variantKey` | Required. Type: `string`. The variant's key. |

### Response

A successful request returns a `200 OK` response and a list of inclusions for the experiment's variant as an array of JSON objects.

#### Request

```bash
curl --request GET \
    --url 'https://experiment.amplitude.com/api/1/experiments/<id>/variants/<variantKey>/users' \
    --header 'Accept: application/json' \
    --header 'Authorization: Bearer <management-api-key>'
```

#### Response

```bash
[
    <user>@<your-company-email>,
    <userId>
]
```

## Get variant cohort inclusions

```bash
GET https://experiment.amplitude.com/api/1/experiments/{id}/variants/{variantKey}/cohorts
```

Fetch a list of cohort inclusions for a specific variant of an experiment.

### Path variables

| Name | Description |
| --- | --- |
| `id` | Required. Type: `string`. The experiment's ID. Find the ID in the URL of the experiment in the Amplitude app. |
| `variantKey` | Required. Type: `string`. The variant's key. |

### Response

A successful request returns a `200 OK` response and a list of cohort inclusions for the experiment's variant as an array of cohort IDs.

#### Request

```bash
curl --request GET \
    --url 'https://experiment.amplitude.com/api/1/experiments/<id>/variants/<variantKey>/cohorts' \
    --header 'Accept: application/json' \
    --header 'Authorization: Bearer <management-api-key>'
```

#### Response

```json
["cohort-id-1", "cohort-id-2"]
```

## Create variant

```bash
POST https://experiment.amplitude.com/api/1/experiments/{id}/variants
```

Create a new variant for an experiment.

### Path variables

| Name | Description |
| --- | --- |
| `id` | Required. String. The experiment's ID. Find the ID in the URL of the experiment in the Amplitude app. |

### Request body

| Name | Description |
| --- | --- |
| `key` | Required. Type: `string`. The variant key. Can only contain letters, numbers, underscores (`_`), and hyphens (`-`). |
| `description` | Optional. Type: `string`. Description for the variant. |
| `name` | Optional. Type: `string`. Name for the variant. |
| `payload` | Optional. Type: `JSON`. Optional payload. Value must be a valid JSON element. |
| `rolloutWeight` | Optional. Type: `number`. Rollout weight for non-targeted users. |

> **Example:** Request
>
> ```json
> {
>   "key": "new-variant-key",
>   "description": "optional description for variant",
>   "name": "optional name for variant",
>   "payload": { "variant-payload": "example payload" },
>   "rolloutWeight": 0
> }
> ```

### Response

A successful request returns a `200 OK` response and `OK` text.

> **Example:** Example request
>
> ```bash
> curl --request POST \
>     --url 'https://experiment.amplitude.com/api/1/experiments/<id>/variants' \
>     --header 'Content-Type: application/json' \
>     --header 'Accept: application/json' \
>     --header 'Authorization: Bearer <management-api-key>' \
>     --data '{"key":"<key>","name":"<name>","description":"<description>","payload":"<payload>","rolloutWeight":<rolloutWeight>}'
> ```

## Edit variant

```bash
PATCH https://experiment.amplitude.com/api/1/experiments/<id>/variants/<variantKey>
```

Edit a variant for an experiment.

### Path variables

| Name | Description |
| --- | --- |
| `id` | Required. Type: `string`. The experiment's ID. Find the ID in the URL of the experiment in the Amplitude app. |
| `variantKey` | Required. Type: `string`. The variant's key. |

### Request body

| Name | Description |
| --- | --- |
| `key` | Optional. Type: `string`. The variant key. Can only contain letters, numbers, underscores (`_`), and hyphens (`-`). |
| `description` | Optional. Type: `string`. Description for the variant. |
| `name` | Optional. Type: `string`. Name for the variant. |
| `payload` | Optional. Type: `JSON`. Optional payload. Value must be a valid JSON element. This value replaces the existing value for the variant payload. |
| `rolloutWeight` | Optional. Type: `number`. Rollout weight for non-targeted users. |

> **Example:** Example request
>
> ```json
> {
>   "key": "updated-variant-key",
>   "description": "updated-optional description for variant",
>   "name": "optional name for variant",
>   "payload": { "variant-payload": "example payload" },
>   "rolloutWeight": 10
> }
> ```

### Response

A successful request returns a `200 OK` response and `OK` text.

> **Example:** Request
>
> ```curl
> curl --request PATCH \
>     --url 'https://experiment.amplitude.com/api/1/experiments/<id>/variants/<variantKey>' \
>     --header 'Content-Type: application/json' \
>     --header 'Accept: application/json' \
>     --header 'Authorization: Bearer <management-api-key>' \
>     --data '{"key":"<key>","name":"<name>","description":"<description>","payload":"<payload>","rolloutWeight":<rolloutWeight>}'
> ```

## Remove variant

```bash
DELETE https://experiment.amplitude.com/api/1/experiments/{id}/variants/{variantKey}
```

Remove a variant from an experiment.

### Path variables

| Name | Description |
| --- | --- |
| `id` | Required. Type: `string`. The experiment's ID. Find the ID in the URL of the experiment in the Amplitude app. |
| `variantKey` | Required. Type: `string`. The variant's key. |

### Response

A successful request returns a `200 OK` response and `OK` text.

> **Example:** Request
>
> ```curl
> curl --request DELETE \
>     --url 'https://experiment.amplitude.com/api/1/experiments/<id>/variants/<variantKey>' \
>     --header 'Accept: application/json' \
>     --header 'Authorization: Bearer <management-api-key>'
> ```

## Add users to variant

```bash
POST https://experiment.amplitude.com/api/1/experiments/{id}/variants/{variantKey}/users
```

Add inclusions (users or devices) to the experiment's variant.

### Path variables

| Name | Description |
| --- | --- |
| `id` | Required. Type: `string`. The experiment's ID. Find the ID in the URL of the experiment in the Amplitude app. |
| `variantKey` | Required. Type: `string`. The variant's key. |

> **Example:** Example request
>
> ```bash
> {
>     "inclusions": [<user1>@<your-company-email>, <user2>@<your-company-email>, <userId>]
> }
> ```

### Request body

| Name | Description |
| --- | --- |
| `inclusions` | Required. Type: `object`. Contains a string array of user or device IDs. |

### Response

A successful request returns a `200 OK` response and `OK` text.

> **Example:** Request
>
> ```curl
> curl --request POST \
>     --url 'https://experiment.amplitude.com/api/1/experiments/<id>/variants/<variantKey>/users' \
>     --header 'Content-Type: application/json' \
>     --header 'Accept: application/json' \
>     --header 'Authorization: Bearer <management-api-key>' \
>     --data '{"inclusions":<["id1", "id2", "id3"]>}'
> ```

## Add cohorts to variant

```bash
POST https://experiment.amplitude.com/api/1/experiments/{id}/variants/{variantKey}/cohorts
```

Add cohort inclusions to the experiment's variant.

### Path variables

| Name | Description |
| --- | --- |
| `id` | Required. Type: `string`. The experiment's ID. Find the ID in the URL of the experiment in the Amplitude app. |
| `variantKey` | Required. Type: `string`. The variant's key. |

### Request body

| Name | Description |
| --- | --- |
| `inclusions` | Required. Type: `array`. An array of cohort IDs to add. |

> **Example:** Example request
>
> ```json
> {
>   "inclusions": ["cohort-id-1", "cohort-id-2"]
> }
> ```

### Response

A successful request returns a `200 OK` response and `OK` text.

> **Example:** Request
>
> ```bash
> curl --request POST \
>     --url 'https://experiment.amplitude.com/api/1/experiments/<id>/variants/<variantKey>/cohorts' \
>     --header 'Content-Type: application/json' \
>     --header 'Accept: application/json' \
>     --header 'Authorization: Bearer <management-api-key>' \
>     --data '{"inclusions":["cohort-id-1", "cohort-id-2"]}'
> ```

## Remove users from variant

```bash
DELETE https://experiment.amplitude.com/api/1/experiments/{id}/variants/{variantKey}/users/{userIndex}
```

Remove inclusions (users or devices) from the experiment's variant.

### Path variables

| Name | Description |
| --- | --- |
| `id` | Required. Type: `string`. The experiment's ID. Find the ID in the URL of the experiment in the Amplitude app. |
| `variantKey` | Required. Type: `string`. The variant's key. |
| `userIndex` | Required. Type: `string`. The user's index. Zero-indexed. Get an index-based array of users from [Get variant inclusions](#get-variant-inclusions). |

### Response

A successful request returns a `200 OK` response and `OK` text.

> **Example:** Request
>
> ```curl
> curl --request DELETE \
>     --url 'https://experiment.amplitude.com/api/1/experiments/<id>/variants/<variantKey>/users/<userIndex>' \
>     --header 'Accept: application/json' \
>     --header 'Authorization: Bearer <management-api-key>'
> ```

## Remove all users from variant

```bash
DELETE https://experiment.amplitude.com/api/1/experiments/{id}/variants/{variantKey}/users
```

Remove all inclusions (users or devices) from the experiment's variant.

### Path variables

| Name | Description |
| --- | --- |
| `id` | Required. Type: `string`. The experiment's ID. Find the ID in the URL of the experiment in the Amplitude app. |
| `variantKey` | Required. Type: `string`. The variant's key. |

### Response

A successful request returns a `200 OK` response and `OK` text.

> **Example:** Request
>
> ```curl
> curl --request DELETE \
>     --url 'https://experiment.amplitude.com/api/1/experiments/<id>/variants/<variantKey>/users' \
>     --header 'Accept: application/json' \
>     --header 'Authorization: Bearer <management-api-key>'
> ```

## Bulk remove users from variant

```bash
DELETE https://experiment.amplitude.com/api/1/experiments/{id}/variants/{variantKey}/bulk-delete-users
```

Bulk remove users or devices from the experiment's variant. Limited to 100 per request.

### Path variables

| Name | Description |
| --- | --- |
| `id` | Required. Type: `string`. The experiment's ID. Find the ID in the URL of the experiment in the Amplitude app. |
| `variantKey` | Required. Type: `string`. The variant's key. |

### Request body

| Name | Description |
| --- | --- |
| `users` | Required. Type: `object`. Contains a string array of user or device IDs. |

### Response

A successful request returns a `200 OK` response and `OK` text.

> **Example:** Request
>
> ```curl
> curl --request DELETE \
>     --url 'https://experiment.amplitude.com/api/1/experiments/<id>/variants/<variantKey>/bulk-delete-users' \
>     --header 'Content-Type: application/json' \
>     --header 'Accept: application/json' \
>     --header 'Authorization: Bearer <management-api-key>' \
>     --data '{"users":<["id1", "id2", "id3"]>}'
> ```

## Bulk remove cohorts from variant

```bash
DELETE https://experiment.amplitude.com/api/1/experiments/{id}/variants/{variantKey}/bulk-delete-cohorts
```

Bulk remove cohorts from the experiment's variant. Limited to 100 per request.

### Path variables

| Name | Description |
| --- | --- |
| `id` | Required. Type: `string`. The experiment's ID. Find the ID in the URL of the experiment in the Amplitude app. |
| `variantKey` | Required. Type: `string`. The variant's key. |

### Request body

| Name | Description |
| --- | --- |
| `users` | Required. Type: `array`. An array of cohort IDs to remove. |

### Response

A successful request returns a `200 OK` response and `OK` text.

> **Example:** Request
>
> ```bash
> curl --request DELETE \
>     --url 'https://experiment.amplitude.com/api/1/experiments/<id>/variants/<variantKey>/bulk-delete-cohorts' \
>     --header 'Content-Type: application/json' \
>     --header 'Accept: application/json' \
>     --header 'Authorization: Bearer <management-api-key>' \
>     --data '{"users":["cohort-id-1", "cohort-id-2"]}'
> ```

## List deployments

```bash
GET https://experiment.amplitude.com/api/1/experiments/{id}/deployments
```

List all deployments for an experiment.

### Path variables

| Name | Description |
| --- | --- |
| `id` | Required. Type: `string`. The experiment's ID. Find the ID in the URL of the experiment in the Amplitude app. |

### Response

A successful request returns a `200 OK` response and an array of JSON objects with the experiment's deployment details.

#### Request

```curl
curl --request GET \
    --url 'https://experiment.amplitude.com/api/1/experiments/<id>/deployments' \
    --header 'Accept: application/json' \
    --header 'Authorization: Bearer <management-api-key>'
```

#### Response

```json
[
    {
        "id": <id>,
        "projectId": <projectId>,
        "label": "rest-api",
        "key": <key>,
        "deleted": false
    }
]
```

## Add deployment

```bash
POST https://experiment.amplitude.com/api/1/experiments/{id}/deployments
```

Add a deployment to an experiment.

### Path variables

| Name | Description |
| --- | --- |
| `id` | Required. String. The experiment's ID. Find the ID in the URL of the experiment in the Amplitude app. |

### Request body

| Name | Description |
| --- | --- |
| `deployments` | Required. Type: `string array`. Contains a string array of deployment IDs. |

> **Example:** Example request
>
> ```json
> {
>   "deployments": ["<deploymentId>"]
> }
> ```

### Response

A successful request returns a `200 OK` response and `OK` text.

> **Example:** Request
>
> ```curl
> curl --request POST \
>     --url 'https://experiment.amplitude.com/api/1/experiments/<id>/deployments' \
>     --header 'Content-Type: application/json' \
>     --header 'Accept: application/json' \
>     --header 'Authorization: Bearer <management-api-key>'
>     --data '{"deployments":[<deploymentId>]}'
> ```

## Remove deployment

```bash
DELETE https://experiment.amplitude.com/api/1/experiments/{id}/deployments/{deploymentId}
```

Remove a deployment from an experiment.

### Path variables

| Name | Description |
| --- | --- |
| `id` | Required. Type: `string`. The experiment's ID. Find the ID in the URL of the experiment in the Amplitude app. |
| `deploymentId` | Required. Type: `string`. The deployment's ID. |

### Response

A successful request returns a `200 OK` response and `OK` text.

> **Example:** Request
>
> ```bash
> curl --request DELETE \
>     --url 'https://experiment.amplitude.com/api/1/experiments/<id>/deployments/<deploymentId>' \
>     --header 'Accept: application/json' \
>     --header 'Authorization: Bearer <management-api-key>'
> ```

## Edit

> **Note:**
>
> Neither Web Experimentation nor Guides and Surveys support editing experiments. Attempts to edit a Web Experimentation or a Guides and Surveys experiment return a `405` error.

```bash
PATCH https://experiment.amplitude.com/api/1/experiments/{id}
```

Edit an experiment.

### Path variables

| Name | Description |
| --- | --- |
| `id` | Required. Type: `string`. The experiment's ID. Find the ID in the URL of the experiment in the Amplitude app. |

### Request body

| Name | Description |
| --- | --- |
| `name` | Optional. Type: `string`. Name. |
| `description` | Optional. Type: `string`. Description. |
| `bucketingKey` | Optional. Type: `string`. The user property to bucket the user by. |
| `bucketingSalt` | Optional. Type: `string`. Bucketing salt. |
| `bucketingUnit` | Optional. Type: `string`. Bucketing unit represented by a group type from the accounts add-on. Used for group level bucketing and analysis. |
| `evaluationMode` | Optional. Type: `string`. Evaluation mode for the experiment, either `local` or `remote`. |
| `rolloutPercentage` | Optional. Type: `number`. Rollout percentage for non-targeted users. Range 0 - 100. |
| `targetSegments` | Optional. Type: `object array`. Refer to the [`targetSegments`](#targetsegments) table for more information. The `targetSegments` object array replaces existing target segments. This option doesn't support cohorts. |
| `enabled` | Optional. Type: `boolean`. Property to activate or deactivate the experiment. |
| `archive` | Optional. Type: `boolean`. Property to archive or unarchive the experiment. |
| `experimentType` | Optional. Type: `string`. Experiment type. Options include `a-b-test` or `multi-arm-bandit`. |
| `stickyBucketing` | Optional. Type: `boolean`. If true, the experiment uses [sticky bucketing](https://amplitude.com/docs/feature-experiment/implementation#sticky-bucketing). |
| `startDate` | Optional. Type: `string`. Start date of the experiment in ISO 8601 format. |
| `endDate` | Optional. Type: `string`. End date of the experiment in ISO 8601 format. End date can be null. |
| `exposureEvent` | Optional. Type: `object`. Refer to the [`exposureEvent`](#exposureevent) table for more information. If set to null, Amplitude uses the Amplitude Exposure Event. |
| `tags` | Optional. Type: `string array`. A list of tags for the experiment. Tags are added and deleted by the same operation. To add new tags to the existing ones, fetch a list of all experiment tags first. |
| `decision` | Optional. Type: `string`. Options include `rollout`, `rollback`, `continue-running`. |
| `decisionReason` | Optional. Type: `string`. The reason for the decision. |
| `rolledOutVariant` | Optional. Type: `string`. The variant key or name that you rolled out. |

#### exposureEvent

| Name | Description |
| --- | --- |
| `event_type` | Required. Type: `string`. Event type. |
| `filters` | Required. Type: `object array`. A list of property filters. Refer to the [`filters`](#filters) table for more information. |

#### filters

| Name | Description |
| --- | --- |
| `group_type` | Optional. Type: `string`. Group type of the filter; can be null. Can be `User` value or one of the group values, like `org_id`, `org name` |
| `subprop_key` | Required. Type: `string`. Filter's key; can be null. |
| `subprop_op` | Required. Type: `string`. The [operation](#subprop_op) to use in this filter. |
| `subprop_type` | Required. Type: `string`. Either `event`, `user` or `group` indicating that the property is either an event, user or group property, respectively. |
| `subprop_value` | Required. Type: `string array`. A list of values to filter the event property by. |

#### subprop\_op

- `is`
- `is not`
- `contains`
- `does not contain`
- `less`
- `less or equal`
- `greater`
- `greater or equal`
- `glob match`
- `glob does not match`

> **Example:** Example request
>
> ```json
> {
>   "name": "updated name",
>   "description": "updated description",
>   "bucketingKey": "amplitude_id",
>   "bucketingSalt": "<bucketingSalt>",
>   "evaluationMode": "remote",
>   "rolloutPercentage": 0,
>   "enabled": true,
>   "experimentType": "a-b-test",
>   "stickyBucketing": false,
>   "startDate": "2023-07-31T10:26:00.996Z",
>   "endDate": "2023-09-23T10:26:00.996Z",
>   "tags": ["prod", "staging"],
>   "exposureEvent": {
>     "event_type": "_active",
>     "filters": [
>       {
>         "group_type": "User",
>         "subprop_key": "amplitude_day_of_week",
>         "subprop_op": "is",
>         "subprop_type": "day_time_prop",
>         "subprop_value": ["Tuesday"]
>       }
>     ]
>   }
> }
> ```

### Response

A successful request returns a `200 OK` response.

> **Example:** Request
>
> ```curl
> curl --request PATCH \
>     --url 'https://experiment.amplitude.com/api/1/experiments/<id>' \
>     --header 'Content-Type: application/json' \
>     --header 'Accept: application/json' \
>     --header 'Authorization: Bearer <management-api-key>' \
>     --data '{"enabled":<enabled>,"rolloutPercentage":<rolloutPercentage>}'
> ```

## Create

```bash
POST https://experiment.amplitude.com/api/1/experiments
```

Create a new feature experiment.

### Request body

| Name | Description |
| --- | --- |
| `projectId` | Required. Type: `string`. The project's ID. |
| `key` | Required. Type: `string`. The flag key. |
| `name` | Optional. Type: `string`. The experiment name. |
| `description` | Optional. Type: `string`. Description for the experiment. |
| `variants` | Optional. Type: `object array`. Array of [`variants`](#variants). |
| `bucketingKey` | Optional. Type: `string`. The user property to bucket the user by. |
| `rolloutWeights` | Optional. Type: `object`. Rollout weights for non-targeted users. The object should be a mapping from variant key to rollout weight as an integer. For example: `{ "control": 1, "treatment": 1 }`. |
| `targetSegments` | Optional. Type: `object array`. Refer to the [`targetSegments`](#targetsegments) table for more information. |
| `deployments` | Optional. Type: `string array`. Array of deployment IDs to assign the experiment to. |
| `evaluationMode` | Optional. Type: `string`. Experiment evaluation mode. Options include `remote` or `local`. |
| `experimentType` | Optional. Type: `string`. Experiment type. Options include `a-b-test` or `multi-arm-bandit`. |

#### variants

The `variants` field contains these objects.

| Name | Description |
| --- | --- |
| `key` | Required. Type: `string`. The key (a.k.a value) of the variant. Can only contain letters, numbers, underscores (`_`), and hyphens (`-`). |
| `payload` | Optional. Type: `JSON`. Optional payload. Value must be a valid JSON element. |
| `name` | Optional. Type: `string`. The variant name. |
| `description` | Optional. Type: `string`. The variant description. |

#### targetSegments

The `targetSegments` field contains these objects.

| Name | Description |
| --- | --- |
| `name` | Required. Type: `string`. The segment name. |
| `conditions` | Required. Type: `object array`. Array of [`conditions`](#conditions). |
| `percentage` | Required. Type: `number`. The allocation percentage for users who match a condition. |
| `rolloutWeights` | Required. Type: `object`. A map from variant key to rollout weight. For example: `{ "control": 1, "treatment": 1 }`. |

#### conditions

The `conditions` field contains these objects.

| Name | Description |
| --- | --- |
| `type` | Required. Type: `string`. **Must have value: `property`** |
| `prop` | Required. Type: `string`. The property to use in the condition. Prefix custom and free-form properties with `gp:` |
| `op` | Required. Type: `string`. The [operation](#op) to use in this condition. |
| `values` | Required. Type: `string array`. The values to use in the operation. |

#### op

A string value representing operations on a property value. Possible values are:

- `is`
- `is not`
- `contains`
- `does not contain`
- `less`
- `less or equal`
- `greater`
- `greater or equal`
- `set is`
- `set is not`
- `set contains`
- `set does not contain`
- `glob match`
- `glob does not match`

> **Example:** Example request
>
> ```json
> {
>   "projectId": "<projectId>",
>   "name": "Analyze button clicks experiment",
>   "key": "analyze-button-clicks-experiment",
>   "description": "analyze button clicks on the main page",
>   "variants": [
>     {
>       "key": "control"
>     },
>     {
>       "key": "treatment"
>     }
>   ],
>   "rolloutWeights": { "control": 1, "treatment": 1 },
>   "targetSegments": [
>     {
>       "name": "Segment 1",
>       "conditions": [
>         {
>           "prop": "country",
>           "op": "is",
>           "type": "property",
>           "values": ["United States"]
>         }
>       ],
>       "percentage": 0,
>       "bucketingKey": "amplitude_id",
>       "rolloutWeights": {
>         "control": 1,
>         "treatment": 1
>       }
>     }
>   ],
>   "deployments": ["<deploymentId>"],
>   "evaluationMode": "remote",
>   "experimentType": "a-b-test"
> }
> ```

### Response

A successful request returns a `200 OK` response and a JSON object with the experiment's id and url.

#### Request

```bash
curl --request POST \
    --url 'https://experiment.amplitude.com/api/1/experiments' \
    --header 'Content-Type: application/json' \
    --header 'Accept: application/json' \
    --header 'Authorization: Bearer <management-api-key>' \
    --data '{"projectId":"<projectId>","key":"<key>"}'
```

#### Response

```json
{
  "id": "<id>",
  "url": "http://experiment.amplitude.com/amplitude/<projectId>/config/<id>"
}
```