experiments

Launch a draft experiment.

Validates the experiment is in draft state, activates its linked feature flag, sets start_date to the current server time, and transitions the experiment to running. Returns 400 if the experiment has already been launched or if the feature flag configuration is invalid (e.g. fewer than 2 variants).

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

Request

  • Base URL: https://us.posthog.com
  • URL: https://us.posthog.com/api/projects/{project_id}/experiments/{id}/launch/
  • 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/.

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.