---
title: "Change experiment status"
method: POST
path: "/experiments/{experiment_id}/status"
tags: ["Experiments"]
---

# Change experiment status

`POST /experiments/{experiment_id}/status`

Changes the status of an experiment (e.g. start, pause, finish).

## Path parameters

- `experiment_id` string, required

## Request body

- V4ExperimentStatusRequest
  - `status` 'draft' | 'active' | 'paused' | 'finished', required — New experiment status.

## Response `200`

Updated experiment with new status.

- 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
- `404` — Experiment not found
- `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)