---
title: "Update Experiment"
method: PATCH
path: "/experiments/{id}"
tags: ["Experiments"]
---

# Update Experiment

`PATCH /experiments/{id}`

Updates the targeting rules, treatment allocation, metrics, or hypothesis of an existing experiment or feature flag. Weights and metrics can only grow, so enrolled users never change arms and an existing metric is never dropped. Lifecycle moves through the transition endpoints (`activate`, `pause`, `end`), never through this update. Requires the corresponding experiment permission on the owning account, or Whop internal access for internal experiments.

## Request body

- object
  - `control` object
    - `related_resource` ExperimentResourceReference
      - `id` string, required — Referenced resource tag, belonging to the experiment owner.
      - `object` 'app' | 'app_build' | 'product' | 'plan', required
  - `hypothesis` string, nullable — Omit to leave unchanged. Send an empty string to clear it. Not accepted on feature flags. When setting it, structure it as "If we [change] for [cohort], then [measurable behavior] will [increase/decrease], resulting in [business outcome], because [evidence]. Created by [name]." same as on create.
  - `related_resource` ExperimentResourceReference
    - `id` string, required — Referenced resource tag, belonging to the experiment owner.
    - `object` 'app' | 'app_build' | 'product' | 'plan', required
  - `targeting_rules` object[] — Replace the targeting rules with this set. Omit to leave unchanged.
    - `conditions` object[], required — Conditions within this rule. Must be non-empty. All conditions must be satisfied for the rule to match (AND logic). Rules are OR-ed together.
      - `field` string, nullable — Property name to read from the user context. Required when `type` is `property`.
      - `operator` 'any' | 'none' | 'eq' | 'neq' | 'gt' | 'gte' | 'lt' | 'lte', required — Comparison to apply: `any`/`none` — inclusion/exclusion list; `eq`/`neq` — equality; `gt`/`gte`/`lt`/`lte` — numeric range.
      - `type` 'user_id' | 'account_id' | 'property', required — `user_id` — match on subject user ID; `account_id` — match on account ID (prefixed `biz_`); `property` — match on a named user property (requires `field`).
      - `value` unknown, required
    - `type` 'include' | 'exclude' — `include` — users matching this rule qualify; `exclude` — users matching this rule are always excluded, overriding any include rule. Defaults to `include`.
  - `variants` object[] — Grow treatment allocation. Pass every existing treatment with an equal-or-higher weight; append new names to add arms. Weights never decrease and arms are never removed. Omit to leave unchanged.
    - `name` string, required — Treatment name. Pass every existing treatment (weights equal or higher); append new names to add arms. `control` is reserved.
    - `related_resource` ExperimentResourceReference
      - `id` string, required — Referenced resource tag, belonging to the experiment owner.
      - `object` 'app' | 'app_build' | 'product' | 'plan', required
    - `weight` integer — Percentage assigned to treatment; allocation may only grow.

## Response `200`

metrics added

- Experiment
  - `account_id` string, required — Owning account ID, or internal for Whop platform experiments.
  - `assignment_seed` string, required — Assignment hashes UTF-8 seed + subject ID with CRC32 modulo 100 and selects the stored end-exclusive range.
  - `bucket_by` 'user' | 'account' | 'anonymous', nullable — Randomization unit — `user` buckets each user independently, `account` buckets whole accounts (every user of an account gets the same arm). `null` for feature flags.
  - `configuration_revision` integer, required — Revision of the serving configuration. Does not change the assignment seed.
  - `control` object, required
    - `related_resource` ExperimentResourceReference
      - `id` string, required — Referenced resource tag, belonging to the experiment owner.
      - `object` 'app' | 'app_build' | 'product' | 'plan', required
  - `created_at` string, nullable — When the experiment was created, as an ISO 8601 timestamp.
  - `created_by` string, nullable — ID of the user who created the experiment, prefixed `user_`. `null` for experiments created before creators were recorded.
  - `ended_at` string, nullable — When the experiment stopped collecting data, as an ISO 8601 timestamp. `null` while still running.
  - `feature_flag_only` boolean, nullable — `true` when this was created as a feature flag rather than a full experiment. Feature flags share the same evaluation API but do not collect metric results.
  - `findings` string, nullable — What was learned and why this outcome, recorded when the experiment was ended. `null` until then.
  - `flag_key` string, required — Developer-chosen handle referenced from code. Anywhere the API takes an experiment identifier, the `expt_` id and the flag_key are interchangeable.
  - `hypothesis` string, nullable — Hypothesis for this experiment. `null` when none is set, and always `null` for feature flags.
  - `id` string, required — Unique identifier for the experiment, prefixed `expt_`.
  - `name` string, required — Human-readable display name.
  - `related_resource` ExperimentResourceReference, required
    - `id` string, required — Referenced resource tag, belonging to the experiment owner.
    - `object` 'app' | 'app_build' | 'product' | 'plan', required
  - `started_at` string, nullable — When the experiment began collecting data, as an ISO 8601 timestamp. `null` for drafts.
  - `status` 'draft' | 'active' | 'paused' | 'ended', required — Lifecycle state. `draft` — not yet live; `active` — currently running; `paused` — traffic paused; `ended` — concluded.
  - `targeting_rules` object[], required — Rules gating who is in the experiment at all. Conditions within a rule are AND-ed, rules are OR-ed, and `exclude` rules always win. Empty means everyone qualifies.
    - `conditions` object[], required — Conditions within this rule, all of which must match.
      - `field` string, nullable — Property name to read from the user context. Present when `type` is `property`.
      - `operator` 'any' | 'none' | 'eq' | 'neq' | 'gt' | 'gte' | 'lt' | 'lte', required — Comparison to apply.
      - `type` 'user_id' | 'account_id' | 'property', required — What the condition matches on: the user ID, the account ID, or a named user property.
      - `value` unknown, required
    - `type` 'include' | 'exclude' — `include` — users matching this rule qualify; `exclude` — users matching this rule are always excluded, overriding any include rule.
  - `updated_at` string, date_time, nullable, required
  - `variants` object[], required — Treatment arms. Users outside every arm's allocation form the implicit `control` group. Weights only ever grow and arms are never removed, so a user moves from control into a treatment at most once.
    - `name` string, required — Treatment identifier. `control` is reserved — it is the implicit remainder.
    - `ranges` array[] — Granted bucket ranges (1% units, end-exclusive) recording this arm's allocation history. Server-managed; ranges are only ever appended, which is what keeps assignments permanent.
      - integer[]
    - `related_resource` ExperimentResourceReference
      - `id` string, required — Referenced resource tag, belonging to the experiment owner.
      - `object` 'app' | 'app_build' | 'product' | 'plan', required
    - `weight` integer, required — Percentage of all users assigned to this treatment, 1–100. All weights together sum to at most 100; the remainder is control.
  - `winning_arm` string, nullable — The treatment that won, set when the experiment was ended. Once set, every evaluation returns this arm to every caller regardless of targeting or allocation, and no further exposures are recorded. `null` means control won — an ended experiment with no winning arm evaluates to `control` for everyone. Always `null` for feature flags, which simply evaluate to disabled once ended.

## Other responses

- `404` — Resource not found

---

[API](https://skmtc.dev/whop/apis/whop-api.md) · [All operations](https://skmtc.dev/whop/apis/whop-api/llms.txt) · [OpenAPI document](https://skmtc.dev/whop/apis/whop-api/revisions/51933d70d7f5?raw)