experiments

Ship a variant and (optionally) end the experiment.

Updates the feature flag so the selected variant gets 100% of the variant distribution. By default, existing release conditions on the flag are preserved untouched — the variant is served only to users who already match them. Pass release_to_everyone: true to also prepend a catch-all release condition that rolls the variant out to 100% of users (overrides any existing release conditions on the flag).

Can be called on both running and stopped experiments. If the experiment is still running, it will also be ended (end_date set and status marked as stopped). If the experiment has already ended, only the flag is rewritten - this supports the "end first, ship later" workflow.

If an approval policy requires review before changes on the flag take effect, the API returns 409 with a change_request_id. The experiment is NOT ended until the change request is approved and the user retries.

Returns 400 if the experiment is in draft state, the variant_key is not found on the flag, or the experiment has no linked feature flag.

post/api/projects/{project_id}/experiments/{id}/ship_variant/

Request

  • Base URL: https://us.posthog.com
  • URL: https://us.posthog.com/api/projects/{project_id}/experiments/{id}/ship_variant/
  • Auth: HTTP bearer

Path parameters

idinteger required

A unique integer value identifying this experiment.

project_idstring required

Project ID of the project you're trying to access. To find the ID of the project, make a call to /api/projects/.

Request body

conclusion_commentstring nullable

Optional comment about the experiment conclusion.

open_cleanup_prboolean

When true, open a draft pull request that removes the experiment's feature-flag code from the linked repository. A personal API key needs the task:write scope (403 otherwise). Skipped when the conclusion is empty, or when no connected repository can be resolved.

repositorystring nullable

GitHub repository to open the cleanup pull request in, in organization/repository format. Only used when open_cleanup_pr is true. It must be one of the team's connected repositories (see the flag_cleanup_target action); it is then saved as the experiment's repository. When omitted, the experiment's saved repository, the team's default cleanup repository, or the team's only connected repository is used.

set_repository_as_team_defaultboolean

When true, also save repository as this environment's default cleanup repository, used for experiments that have no repository of their own. Only acts when open_cleanup_pr is true and repository is provided and belongs to the team's GitHub installation. Requires project admin access (403 otherwise).

variant_keystring required

The key of the variant to ship.

release_to_everyoneboolean

If true, prepend a release condition to the feature flag that rolls the variant out to 100% of users, overriding any existing release conditions on the flag. If false (default), only update the variant distribution — existing release conditions are preserved and the variant is served only to users who already match them.

Response

idinteger required
namestring required

Name of the experiment.

descriptionstring nullable

Description of the experiment hypothesis and expected outcomes.

start_datestring date-time nullable
end_datestring date-time nullable
feature_flag_keystring required

Unique key for the experiment's feature flag. Letters, numbers, hyphens, and underscores only. Search existing flags with the feature-flag-get-all tool first — reuse an existing flag when possible.

holdout_idinteger nullable

ID of a holdout group to exclude from the experiment.

exposure_cohortinteger nullable required
excluded_variantsstring[] nullable

Variant keys to exclude from metric result calculations. Excluded variants are still served to users but omitted from statistical analysis. The baseline variant and holdout pseudo-variants cannot be excluded. Canonical home for what historically lived in parameters.excluded_variants.

secondary_metricsunknown
filtersunknown
archivedboolean

Whether the experiment is archived.

deletedboolean nullable
created_atstring date-time required
updated_atstring date-time required
stats_configunknown
scheduling_configunknown
allow_unknown_eventsboolean

Suppresses the validation that rejects metrics referencing events not yet ingested by this project. REQUIRES explicit user confirmation before being set to true — never flip this silently to retry a failed call. The default validation catches typo'd event names and missing instrumentation. Set this to true only when the user has confirmed the event is intentional (e.g. they are about to instrument it).

_create_in_folderstring
conclusion_commentstring nullable

Comment about the experiment conclusion.

flag_cleanup_task_idstring uuid nullable required

ID of the Desktop task opened to remove the experiment's feature-flag code, when one was requested via open_cleanup_pr on end/ship_variant. Read its status via the flag_cleanup_task action.

repositorystring nullable

GitHub repository holding this experiment's feature-flag code, in organization/repository format. Used as the target of the flag-cleanup pull request opened via open_cleanup_pr on end/ship_variant. When not set, cleanup targets the team's only connected repository and is skipped if the team has several.

primary_metrics_ordered_uuidsstring[] nullable

Display order of the primary metrics, as metric uuids. This is a display hint only: a metric not in the list renders after the listed ones in stored order, and an entry that matches no metric is ignored. Send it only to reorder metrics. Adding or removing metrics does not need it.

secondary_metrics_ordered_uuidsstring[] nullable

Display order of the secondary metrics, as metric uuids. This is a display hint only: a metric not in the list renders after the listed ones in stored order, and an entry that matches no metric is ignored. Send it only to reorder metrics. Adding or removing metrics does not need it.

only_count_matured_usersboolean
update_feature_flag_paramsboolean

When true, sync the flag config sent in this request (via the feature_flag object) to the linked feature flag. Draft experiments always sync regardless. On a running experiment, feature_flag config without this flag is rejected.

versioninteger nullable

Optimistic-concurrency token. Reads return the experiment's current version, bumped on every update. Send the version you last read with an update to detect concurrent edits: a stale update merges concurrent changes where safe — metric collections per metric uuid, other fields per field — using the base values sent in original_experiment, and fails with HTTP 409 only when the same metric or field changed on both sides (or no base value was sent for a changed field). Omit to skip the check.

original_experimentobject nullable

The experiment state as the client last read it, used together with version to resolve concurrent edits: metric collections merge per metric uuid, and any other field the update carries merges per field against its base value here (only a same-field double edit fails). Relevant keys are metrics, metrics_secondary, saved_metrics_ids, plus the last-read values of whichever scalar fields the update writes; unknown keys are ignored. Changed fields without a base value — and, without this object, any version mismatch — fail with HTTP 409.

status'draft' | 'running' | 'paused' | 'exposure_frozen' | 'stopped' required
is_legacyboolean required

Whether the experiment uses any legacy-engine metrics (ExperimentTrendsQuery or ExperimentFunnelsQuery). Used to flag legacy experiments and gate actions that don't support them, such as duplicate and copy-to-project.

can_freeze_exposureboolean required

Whether enrollment can be frozen right now: the experiment must be running (not draft, paused, stopped, or already frozen) and its feature flag must have release conditions that a person cohort can narrow (no group aggregation, no holdout, no early access conditions).

resolved_exposure_eventstring required

The event exposures are actually counted on when the experiment doesn't configure a custom one — $feature_flag_called, or $experiment_exposure once the team is in the rollout and the experiment started at or after the cutoff. Resolved server-side so clients display the same event the results queries read. For a draft, this is what the experiment would resolve to if launched now.

user_access_levelstring nullable required

The effective access level the user has for this object

tagsstring[]

Organizational tags for this experiment (up to 100, 255 characters each).

Changes

No recorded changes to this operation across all 1 revision of this API.