Experiments
For instructions on how to authenticate to use this endpoint, see API overview.
Endpoints
GET | |
POST | |
GET | |
PATCH | |
DELETE | |
GET | |
POST | |
POST | |
POST | |
POST | |
POST | |
GET | |
GET | |
POST | |
GET | |
GET | |
GET | |
POST | |
POST |
List all experiments
List experiments for the current project. Supports filtering by status and archival state.
Required API key scopes
experiment:readQuery parameters
- archivedboolean
- created_by_idstring
- eventstring
- excluded_tagsstring
- feature_flag_idinteger
- limitinteger
- offsetinteger
- orderstring
- prompt_namestring
- searchstring
- statusstringOne of:
"all""complete""draft""exposure_frozen""paused""running""stopped" - tagsstring
Response
Example request
GET Example response
Status 200
Create experiments
Also available via the PostHog MCP server:
experiment-create— Create experiment
Create a new experiment in draft status with optional metrics.
Required API key scopes
experiment:writeRequest parameters
- namestring
- descriptionstring | null
- start_datestring | null
- end_datestring | null
- feature_flag_keystring
- feature_flag
- holdout_idinteger | null
- parameters
- running_time_calculation
- excluded_variantsarray | null
- secondary_metrics
- saved_metrics_idsarray | null
- filters
- archivedbooleanDefault:
false - deletedboolean | null
- type
- exposure_criteria
- metrics
- metrics_secondary
- stats_config
- scheduling_config
- allow_unknown_eventsbooleanDefault:
false - _create_in_folderstring
- conclusion
- conclusion_commentstring | null
- repositorystring | null
- primary_metrics_ordered_uuidsarray | null
- secondary_metrics_ordered_uuidsarray | null
- only_count_matured_usersboolean
- update_feature_flag_paramsbooleanDefault:
false - versioninteger | null
- original_experimentobject | null
- tagsarray
Response
Example request
POST Example response
Status 201
Retrieve experiments
Also available via the PostHog MCP server:
experiment-get— Get experiment details
Retrieve a single experiment by ID, including its current status, metrics, feature flag, and results metadata.
Required API key scopes
experiment:readPath parameters
- idinteger
Response
Example request
GET Example response
Status 200
Update experiments
Also available via the PostHog MCP server:
experiment-update— Update experiment
Update an experiment. Use this to modify experiment properties such as name, description, metrics, variants, and configuration. Metrics can be added, changed and removed at any time. Feature-flag config (variants, rollout, payloads) is sent via the feature_flag object.
Required API key scopes
experiment:writePath parameters
- idinteger
Request parameters
- namestring
- descriptionstring | null
- start_datestring | null
- end_datestring | null
- feature_flag_keystring
- feature_flag
- holdout_idinteger | null
- parameters
- running_time_calculation
- excluded_variantsarray | null
- secondary_metrics
- saved_metrics_idsarray | null
- filters
- archivedbooleanDefault:
false - deletedboolean | null
- type
- exposure_criteria
- metrics
- metrics_secondary
- stats_config
- scheduling_config
- allow_unknown_eventsbooleanDefault:
false - _create_in_folderstring
- conclusion
- conclusion_commentstring | null
- repositorystring | null
- primary_metrics_ordered_uuidsarray | null
- secondary_metrics_ordered_uuidsarray | null
- only_count_matured_usersboolean
- update_feature_flag_paramsbooleanDefault:
false - versioninteger | null
- original_experimentobject | null
- tagsarray
Response
Example request
PATCH Example response
Status 200
Delete experiments
Hard delete of this model is not allowed. Use a patch API call to set "deleted" to true
Required API key scopes
experiment:writePath parameters
- idinteger
Example request
DELETE Example response
Status 405 No response body
Retrieve experiments activity
Change history for this experiment.
Returns a paginated audit trail of changes to the experiment, its holdouts and shared metrics, and its linked feature flag: who made each change, what changed (field-level before/after values), and when. Ordered newest first.
Required API key scopes
activity_log:readPath parameters
- idinteger
Query parameters
- limitintegerDefault:
10 - pageintegerDefault:
1
Response
Example request
GET Example response
Status 200
Status 404 No response body
Create experiments archive
Archive an ended experiment.
Hides the experiment from the default list view. The experiment can be restored at any time by updating archived=false. When the linked feature flag is still enabled, pass disable_feature_flag=true to also disable and archive it. Returns 400 if the experiment is already archived or has not ended yet.
Required API key scopes
experiment:writePath parameters
- idinteger
Request parameters
- disable_feature_flagbooleanDefault:
false
Response
Example request
POST Example response
Status 200
Create experiments copy to project
Copy an experiment into another project in the same organization as a new draft.
Required API key scopes
experiment:writePath parameters
- idinteger
Request parameters
- target_team_idinteger
- feature_flag_keystring
- namestring
Response
Example request
POST Example response
Status 200
Create experiments create exposure cohort for experiment
Mixin for ViewSets to handle approval-gate exceptions raised from decorated serializers.
Intercepts ApprovalRequired (409) and PolicyConflict (400) raised by the @approval_gate decorator on serializer methods and converts them into the same responses the viewset path produces (see decorators._result_to_response), so both paths share one contract.
Required API key scopes
experiment:writePath parameters
- idinteger
Request parameters
- namestring
- descriptionstring | null
- start_datestring | null
- end_datestring | null
- feature_flag_keystring
- holdout_idinteger | null
- parameters
- running_time_calculation
- excluded_variantsarray | null
- secondary_metrics
- saved_metrics_idsarray | null
- filters
- archivedbooleanDefault:
false - deletedboolean | null
- type
- exposure_criteria
- metrics
- metrics_secondary
- stats_config
- scheduling_config
- allow_unknown_eventsbooleanDefault:
false - _create_in_folderstring
- conclusion
- conclusion_commentstring | null
- repositorystring | null
- primary_metrics_ordered_uuidsarray | null
- secondary_metrics_ordered_uuidsarray | null
- only_count_matured_usersboolean
- update_feature_flag_paramsbooleanDefault:
false - versioninteger | null
- original_experimentobject | null
- tagsarray
Example request
POST Example response
Status 200 No response body
Create experiments duplicate
Mixin for ViewSets to handle approval-gate exceptions raised from decorated serializers.
Intercepts ApprovalRequired (409) and PolicyConflict (400) raised by the @approval_gate decorator on serializer methods and converts them into the same responses the viewset path produces (see decorators._result_to_response), so both paths share one contract.
Required API key scopes
experiment:writePath parameters
- idinteger
Request parameters
- namestring
- descriptionstring | null
- start_datestring | null
- end_datestring | null
- feature_flag_keystring
- holdout_idinteger | null
- parameters
- running_time_calculation
- excluded_variantsarray | null
- secondary_metrics
- saved_metrics_idsarray | null
- filters
- archivedbooleanDefault:
false - deletedboolean | null
- type
- exposure_criteria
- metrics
- metrics_secondary
- stats_config
- scheduling_config
- allow_unknown_eventsbooleanDefault:
false - _create_in_folderstring
- conclusion
- conclusion_commentstring | null
- repositorystring | null
- primary_metrics_ordered_uuidsarray | null
- secondary_metrics_ordered_uuidsarray | null
- only_count_matured_usersboolean
- update_feature_flag_paramsbooleanDefault:
false - versioninteger | null
- original_experimentobject | null
- tagsarray
Example request
POST Example response
Status 200 No response body
Create experiments end
End a running experiment without shipping a variant.
Sets end_date to now and marks the experiment as stopped. The feature flag is NOT modified — users continue to see their assigned variants and exposure events ($feature_flag_called) continue to be recorded. However, only data up to end_date is included in experiment results.
Use this when:
- You want to freeze the results window without changing which variant users see.
- A variant was already shipped manually via the feature flag UI and the experiment just needs to be marked complete.
The end_date can be adjusted after ending via PATCH if it needs to be backdated (e.g. to match when the flag was actually paused).
Other options:
- Use ship_variant to end the experiment AND roll out a single variant to 100%% of users.
- Use pause to deactivate the flag without ending the experiment (stops variant assignment but does not freeze results).
Returns 400 if the experiment is not running.
Required API key scopes
experiment:writePath parameters
- idinteger
Request parameters
- conclusion
- conclusion_commentstring | null
- open_cleanup_prbooleanDefault:
false - repositorystring | null
- set_repository_as_team_defaultbooleanDefault:
false
Response
Example request
POST Example response
Status 200
Retrieve experiments flag cleanup target
Repository a flag-cleanup pull request for this experiment would be opened in.
Resolution order: the experiment's saved repository, else the environment's default
cleanup repository, else the team's only connected GitHub repository. When the team
has several repositories and none is saved (source=ambiguous), pass one via
repository on end/ship_variant.
Required API key scopes
experiment:readPath parameters
- idinteger
Response
Example request
GET Example response
Status 200
Retrieve experiments flag cleanup task
Status of the flag-cleanup Desktop task opened for this experiment.
When an experiment was ended or shipped with open_cleanup_pr=true, a Desktop task removes the experiment's feature-flag code and opens a draft pull request. This returns that task's latest run status and the PR URL once one is opened. Poll until is_terminal is true. Returns 404 when no cleanup task was opened.
Required API key scopes
experiment:readPath parameters
- idinteger
Response
Example request
GET Example response
Status 200
Create experiments freeze exposure
Freeze exposure on a running experiment while metrics keep flowing.
Snapshots the already-exposed users into a static cohort and narrows the
linked feature flag so only those users keep matching — new users can no
longer enter the experiment. end_date is left null so long-term metrics
(revenue/LTV/renewals/retention) keep accumulating. Enrolled users keep
their assigned variant. The serialized status becomes 'exposure_frozen'.
Returns 400 if the experiment is not running, exposure is already frozen, the experiment is group-aggregated (group flags cannot be frozen with a person cohort), or the exposed set is too large to snapshot synchronously.
Required API key scopes
experiment:writePath parameters
- idinteger
Response
Example request
POST Example response
Status 200
Retrieve experiments health
Health check findings for this experiment: problems in its configuration and its feature flag that keep it from producing trustworthy results, each with a fix.
The checks here read the experiment, its flag, its linked metrics, and the changes of the
flag's variant split since launch. The checks that read exposure counts come with the
exposure query. The split-change check compares the split changes with the exposures only
for exposure criteria that name an event without property filters. When the split changed
after launch and the criteria have filters or an action, or an API key lacks query:read,
it returns an info finding with the subcode not_checked and the cause in
evidence.reason. A caller who can't view the linked flag's history (viewer access to the
flag and, with an API key, activity_log:read) gets that finding for every running
experiment, because the changes are not read.
The severity of the some_conditions_pinned finding follows the largest share that the
users of the pinned release conditions make up among the users who got one variant from
the flag, in the last 7 days, or since launch or the flag's last save if later. It reads
the flag's calls that name the matched condition, not the experiment's exposure criteria:
info up to 5%, warning above, and no finding under 1% when at least half of the calls
that returned a variant name a condition. The finding is info when the share is unknown,
and evidence.reason says why: not_measured (for example an API key without
query:read, or a caller denied a flag call property), too_few_people (under 100), or
evaluated_outside_flag_service (most calls come from local evaluation, a bootstrap or
the caller's own assignment). A pin to a variant with 0% in the split adds an info,
because that variant's results show only the pinned users, unless the experiment
excludes the variant from the analysis.
Two findings say that the variants are assigned outside PostHog, as info. A running
experiment whose flag has a 0% rollout gets assigned_outside_flag_service instead of
running_but_no_rollout when 10 or more people got a variant from flag calls without a
flag version that are no local evaluation, from an hour after the window starts. When
every condition that includes users pins the variant whose key one property holds,
assigned_by_property replaces all_conditions_pinned.
Required API key scopes
experiment:readPath parameters
- idinteger
Response
Example request
GET Example response
Status 200
Retrieve experiments health inputs
Staff only. The inputs that the health checks read for this reader, to debug why a finding shows or not:
the context of the checks in health, the exposure query's answer that the exposure checks read, and facts
about the project from the setup context's providers (the team's experiment defaults and which SDKs call
flags). The exposure answer comes from the cache. When it is missing or stale, a calculation starts in the
background and exposures.status says so.
Required API key scopes
experiment:readPath parameters
- idinteger
Response
Example request
GET Example response
Status 200
Retrieve experiments in session exposure
How the recordings tab's in-session exposure scope reads on this experiment.
Resolved through the same seam as the recordings query's in_session refusal, so the
scope control disables exactly what a query would be refused for, and the copy can say
when sessions are matched on the stamped flag property rather than on the exposure event.
Postgres reads only, so it can serve the tab's mount path.
Required API key scopes
experiment:readPath parameters
- idinteger
Response
Example request
GET Example response
Status 200
Create experiments launch
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).
Required API key scopes
experiment:writePath parameters
- idinteger
Response
Example request
POST Example response
Status 200
Create experiments metrics recalculation
Trigger a batch recalculation of all metrics for this experiment.
Returns 201 with the new pending recalculation, or 200 with the active one if a recalculation is
already pending or in progress for this experiment. A manual trigger within five minutes after the latest
completed run finished returns 429 with a Retry-After header. The response payload intentionally does not
include the results array — at POST time the workflow has just been queued and no per-metric
results exist yet. Clients should poll GET metrics_recalculation/{id}/ for results as the workflow
progresses.
Required API key scopes
experiment:writePath parameters
- idinteger
Request parameters
- triggerDefault:
manual
Response
Example request
POST