---
title: "POST /api/v1/environments/{environment_api_key}/experiments/"
method: POST
path: "/api/v1/environments/{environment_api_key}/experiments/"
tags: ["mcp"]
---

# POST /api/v1/environments/{environment_api_key}/experiments/

`POST /api/v1/environments/{environment_api_key}/experiments/`

(Beta) Creates an experiment for a multivariate feature. Metrics can be attached inline. Only one active experiment per feature is allowed.

## Path parameters

- `environment_api_key` string, required

## Request body

- Experiment
  - `id` integer
  - `feature` integer, required
  - `name` string, required
  - `hypothesis` string, required
  - `status` 'created' | 'running' | 'paused' | 'completed' — * `created` - Created * `running` - Running * `paused` - Paused * `completed` - Completed
  - `metrics` ExperimentMetricInline[]
    - `metric` string, required
    - `expected_direction` 'increase' | 'decrease' | 'not_increase' | 'not_decrease', required — * `increase` - Increase * `decrease` - Decrease * `not_increase` - Should not increase * `not_decrease` - Should not decrease
  - `experiment_rollout` ExperimentRollout
    - `enabled` boolean, required
    - `rollout_percentage` number, double, required
    - `feature_state_value` FeatureValue, required
      - `type` 'integer' | 'string' | 'boolean', required — * `integer` - integer * `string` - string * `boolean` - boolean
      - `value` string, required
    - `multivariate_feature_state_values` MultivariateValue[]
      - `multivariate_feature_option` integer, required
      - `percentage_allocation` number, double, required
  - `created_at` string, date-time
  - `updated_at` string, date-time
  - `started_at` string, date-time, nullable
  - `ended_at` string, date-time, nullable

## Response `201`

- Experiment
  - `id` integer
  - `feature` integer, required
  - `name` string, required
  - `hypothesis` string, required
  - `status` 'created' | 'running' | 'paused' | 'completed' — * `created` - Created * `running` - Running * `paused` - Paused * `completed` - Completed
  - `metrics` ExperimentMetricInline[]
    - `metric` string, required
    - `expected_direction` 'increase' | 'decrease' | 'not_increase' | 'not_decrease', required — * `increase` - Increase * `decrease` - Decrease * `not_increase` - Should not increase * `not_decrease` - Should not decrease
  - `experiment_rollout` ExperimentRollout
    - `enabled` boolean, required
    - `rollout_percentage` number, double, required
    - `feature_state_value` FeatureValue, required
      - `type` 'integer' | 'string' | 'boolean', required — * `integer` - integer * `string` - string * `boolean` - boolean
      - `value` string, required
    - `multivariate_feature_state_values` MultivariateValue[]
      - `multivariate_feature_option` integer, required
      - `percentage_allocation` number, double, required
  - `created_at` string, date-time
  - `updated_at` string, date-time
  - `started_at` string, date-time, nullable
  - `ended_at` string, date-time, nullable

---

[API](https://skmtc.dev/flagsmith/apis/flagsmith-api.md) · [All operations](https://skmtc.dev/flagsmith/apis/flagsmith-api/llms.txt) · [OpenAPI document](https://skmtc-service-production.skmtc.workers.dev/v1/apis/flagsmith/flagsmith-api/revisions/5a8154d05269/schema)