---
title: "Create an experiment"
method: POST
path: "/experiments"
tags: ["Experiments"]
---

# Create an experiment

`POST /experiments`

Creates a new experiment. Returns 201 with the created experiment and Location header.

## Request body

- V4ExperimentCreateRequest
  - `name` string, required — Experiment display name.
  - `alias_id` string, required — Stable identifier for the experiment. Alphanumeric, hyphens, underscores, dots. Max 64 characters.
  - `description` string — Optional experiment description.
  - `segment_percent` number, nullable — Percentage of users to include in the experiment.
  - `primary_metric` string, nullable — Primary success metric.
  - `goal_value` number, nullable — Target value for the primary metric.
  - `goal_direction` string, nullable — Desired direction of change.
  - `context_key` string — Context key for context-specific experiments.
  - `is_context_specific` boolean — Whether this experiment is restricted to a specific context.

## Response `201`

Experiment created.

- V4Experiment
  - `object` string
  - `id` string — Experiment identifier (server-generated UID).
  - `url` string — Canonical API path.
  - `name` string — Experiment display name.
  - `alias_id` string — User-facing stable identifier (supplied on POST, immutable after). Added in the DEV-777 response audit; was missing from the public envelope despite being accepted on create.
  - `description` string — Experiment description.
  - `status` string — Current experiment status.
  - `started_at` string, date-time, nullable — ISO 8601 timestamp when the experiment was started.
  - `finished_at` string, date-time, nullable — ISO 8601 timestamp when the experiment was finished.
  - `segment_percent` number, nullable — Percentage of users included in the experiment.
  - `primary_metric` string, nullable — Primary success metric. Legacy experiments created before the underscore naming may return hyphenated variants (e.g. `user-to-trial`, `subscription-cancellation`); treat them as read-only and migrate to the underscore form before sending them back on PATCH.
  - `goal_value` number, nullable — Target value for the primary metric.
  - `goal_direction` string, nullable — Desired direction of change for the primary metric.
  - `context_key` string — Context key for context-specific experiments.
  - `is_context_specific` boolean — Whether this experiment is restricted to a specific context.
  - `created_at` string, date-time — ISO 8601 creation timestamp.
  - `updated_at` string, date-time — ISO 8601 last update timestamp.

## Other responses

- `400` — Invalid request
- `401` — Unauthorized
- `415` — Unsupported Content-Type
- `429` — Too many requests
- `502` — Upstream service failure
- `504` — Upstream timeout

---

[API](https://skmtc.net/qonversion/apis/qonversion-rest-api-v4.md) · [All operations](https://skmtc.net/qonversion/apis/qonversion-rest-api-v4/llms.txt) · [OpenAPI document](https://skmtc-service-staging.skmtc.workers.dev/v1/apis/qonversion/qonversion-rest-api-v4/versions/e3f72cf8951c/schema)