:hedgehog: PostHog is the leading platform for building self-driving products. Our developer tools – AI observability, analytics, session replay, flags, experiments, error tracking, logs, and more – capture all the context agents need to diagnose problems, uncover opportunities, and ship fixes. Steer it all from Slack, web, desktop, or the MCP.
Python ab-testingai-analyticsanalyticscdpdata-warehouseexperimentsfeature-flagsjavascriptproduct-analyticspythonreactsession-replaysurveystypescriptweb-analytics
"""
TEMPORARY: This file is in transition.
Current state: Moved from ee/clickhouse/views/experiments.py to products/experiments/backend/presentation/
to break down the monolith incrementally. Serializers split into serializers.py (PR #2) but this file
still directly imports from service/models layers (violating product architecture temporarily).
This will be refactored incrementally in subsequent PRs to match the product architecture pattern.
"""
import json
import asyncio
import logging
from collections.abc import Mapping
from typing import Any, Literal, cast
from django.conf import settings
from django.db.models import BooleanField, Case, Exists, OuterRef, Prefetch, Q, QuerySet, Value, When
from django.utils.text import slugify
from drf_spectacular.utils import OpenApiParameter, OpenApiResponse, extend_schema, extend_schema_view
from loginas.utils import is_impersonated_session
from opentelemetry import trace
from rest_framework import serializers, viewsets
from rest_framework.exceptions import NotFound, PermissionDenied, ValidationError
from rest_framework.request import Request
from rest_framework.response import Response
from posthog.api.cohort import CohortSerializer
from posthog.api.forbid_destroy_model import ForbidDestroyModel
from posthog.api.mixins import ValidatedRequest, validated_request
from posthog.api.routing import TeamAndOrgViewSetMixin
from posthog.api.tagged_item import TaggedItemViewSetMixin
from posthog.api.utils import action
from posthog.auth import ProjectSecretAPIKeyAuthentication
from posthog.helpers.impersonation import get_original_user_from_session
from posthog.models.activity_logging.activity_log import ActivityLog, get_activity_page
from posthog.models.activity_logging.activity_page import ActivityLogPaginatedResponseSerializer, activity_page_response
from posthog.models.organization import OrganizationMembership
from posthog.models.team.team import Team
from posthog.models.user import User
from posthog.permissions import (
get_authenticator_scoped_team_ids,
get_authenticator_scopes,
is_scout_sandbox_request,
is_service_auth,
posthog_feature_flag_enabled,
)
from posthog.rate_limit import (
ClickHouseBurstRateThrottle,
ClickHouseSustainedRateThrottle,
PersonalOrProjectSecretApiKeyRateThrottle,
ProjectSecretApiKeyTeamRateThrottle,
SessionBucketsBurstRateThrottle,
SessionBucketsSustainedRateThrottle,
SessionContextsBurstRateThrottle,
SessionContextsSustainedRateThrottle,
SessionEventDeltasBurstRateThrottle,
SessionEventDeltasSustainedRateThrottle,
)
from posthog.scopes import scopes_not_covered
from posthog.session_recordings.models.session_recording import SessionRecording
from posthog.temporal.common.client import sync_connect
from posthog.temporal.experiments.models import ExperimentTimeseriesRecalculationWorkflowInputs
from posthog.user_permissions import UserPermissions
from products.access_control.backend.facade.api import (
get_restricted_properties_with_group_type_index_for_team,
split_restricted_property_names,
)
from products.access_control.backend.facade.user_access_control import (
UserAccessControl,
access_level_satisfied_for_resource,
)
from products.access_control.backend.presentation.access_control import AccessControlViewSetMixin
from products.approvals.backend.presentation.mixins import ApprovalHandlingMixin
from products.experiments.backend.experiment_service import ExperimentService, ExperimentVersionConflict
from products.experiments.backend.facade.api import (
get_experiment_health,
get_experiment_health_inputs,
get_running_time_target,
)
from products.experiments.backend.facade.contracts import (
ExperimentHealthReaderAccess,
LegacyMigrationError,
RunningTimeMode,
)
from products.experiments.backend.facade.legacy_migration import migrate_experiment as migrate_legacy_experiment
from products.experiments.backend.facade.replay import resolve_in_session_exposure_semantics
from products.experiments.backend.llm_metric_templates import build_template, list_templates
# TODO: Route through facade instead of direct import
from products.experiments.backend.models.experiment import (
LEGACY_METRIC_KINDS,
Experiment,
ExperimentMetricsRecalculation,
ExperimentSavedMetric,
ExperimentTimeseriesRecalculation,
ExperimentToSavedMetric,
experiment_has_legacy_metrics,
)
from products.experiments.backend.presentation.scout_writes import (
is_true,
refuse_scout_cleanup_pr,
refuse_scout_experiment_copy_to_project,
refuse_scout_experiment_delete,
refuse_scout_experiment_migrate,
refuse_scout_live_flag_config_change,
refuse_scout_ship_variant_without_flag_write,
update_carries_flag_config,
)
from products.experiments.backend.presentation.serializers import (
ArchiveExperimentSerializer,
CopyExperimentToProjectSerializer,
CreateFromPromptInputSerializer,
EndExperimentSerializer,
ExperimentActivityQuerySerializer,
ExperimentBasicSerializer,
ExperimentFlagCleanupTargetSerializer,
ExperimentFlagCleanupTaskSerializer,
ExperimentHealthInputsSerializer,
ExperimentHealthSerializer,
ExperimentInSessionExposureSerializer,
ExperimentMatchingIdsResponseSerializer,
ExperimentMetricsRecalculationJobSerializer,
ExperimentMetricsRecalculationLatestSerializer,
ExperimentMetricsRecalculationRunSerializer,
ExperimentSerializer,
ExperimentSessionBucketRequestSerializer,
ExperimentSessionBucketResponseSerializer,
ExperimentSessionContextResponseSerializer,
ExperimentSessionContextsRequestSerializer,
ExperimentSessionContextsResponseSerializer,
ExperimentSessionEventDeltaRequestSerializer,
ExperimentSessionEventDeltaResponseSerializer,
ExperimentSetupContextInputSerializer,
ExperimentSetupContextResponseSerializer,
ExperimentWriteSerializer,
RecalculateMetricsRequestSerializer,
RunningTimeCalculationInputSerializer,
RunningTimeCalculationResultSerializer,
RunningTimeTargetQuerySerializer,
RunningTimeTargetSerializer,
ShipVariantSerializer,
)
from products.experiments.backend.recalculation import (
build_job_payload,
build_timeseries_cold_start_payload,
get_active_recalculation,
get_latest_recalculation,
get_recalculation_by_id,
get_run_results,
request_recalculation,
start_metrics_recalculation_workflow,
)
from products.experiments.backend.running_time_calculator import (
BaselineStats,
calculate_baseline_value,
calculate_running_time_days,
calculate_sample_size,
calculate_variance,
calculate_variance_from_stats,
)
from products.experiments.backend.session_buckets import (
ExperimentSessionBucket,
SessionBucketUnavailable,
finalize_session_bucket,
get_experiment_session_bucket,
)
from products.experiments.backend.session_context import get_session_experiment_context, get_session_experiment_contexts
from products.experiments.backend.session_event_deltas import (
EXPERIMENT_BEHAVIOR_COMPARISON_FLAG,
SessionEventDeltasUnavailable,
all_card_session_ids,
finalize_watch_cards,
get_experiment_session_event_deltas,
)
from products.experiments.backend.setup_context import (
EXPERIMENT_SETUP_CONTEXT_FLAG,
SetupContextInputs,
build_setup_context,
)
from products.feature_flags.backend.models.evaluation_context import FeatureFlagEvaluationContext
from products.feature_flags.backend.models.feature_flag import FeatureFlag
from products.tasks.backend.facade import api as tasks_facade
logger = logging.getLogger(__name__)
tracer = trace.get_tracer(__name__)
# Heavy JSON columns the list view never renders. Deferred for the list action so large
# pages don't pay to read/decode detail-only data; the full serializer still loads them
# for retrieve/update. None of these are touched by the list filters or status derivation.
LIST_DEFERRED_FIELDS = (
"metrics",
"metrics_secondary",
"secondary_metrics",
"exposure_criteria",
"stats_config",
"scheduling_config",
"filters",
"primary_metrics_ordered_uuids",
"secondary_metrics_ordered_uuids",
)
# The viewset's `list` method shadows the builtin `list` in the class namespace, so a
# `list[str]` annotation there resolves to that method (a runtime crash, and a mypy error).
# Reference this module-level alias instead.
RequiredScopes = list[str]
def flag_evaluation_contexts_prefetch() -> Prefetch:
return Prefetch(
"feature_flag__flag_evaluation_contexts",
queryset=FeatureFlagEvaluationContext.objects.select_related("evaluation_context"),
)
def list_is_legacy_annotation() -> Case:
"""DB-side `is_legacy` for the list endpoint, mirroring ``experiment_has_legacy_metrics`` in SQL.
The list serializer omits metrics, so it can't compute legacy-ness in Python without
re-reading the deferred JSON columns (one query per row). Instead we annotate the flag in the
single list query: a JSONB containment check on the inline metrics plus an ``EXISTS`` over the
saved metrics. The metric columns are referenced only in the predicate, so they stay out of the
SELECT output and the response — the deferral still holds.
"""
inline_legacy = Q()
for kind in LEGACY_METRIC_KINDS:
inline_legacy |= Q(metrics__contains=[{"kind": kind}]) | Q(metrics_secondary__contains=[{"kind": kind}])
saved_legacy = Exists(
ExperimentToSavedMetric.objects.filter(
experiment=OuterRef("pk"),
saved_metric__query__kind__in=LEGACY_METRIC_KINDS,
)
)
return Case(
When(inline_legacy | saved_legacy, then=Value(True)),
default=Value(False),
output_field=BooleanField(),
)
def _build_prompt_variants(versions: list[int]) -> list[dict[str, Any]]:
"""Build N feature flag variants from an ordered list of prompt versions.
First variant is keyed "control", matching the codebase's baseline convention (the
baseline defaults to 'control' when present). For the standard 2-variant case the
second is keyed "test", matching the rest of the codebase's defaults. For N >= 3 the
trailing variants are keyed "test-1", "test-2", … so each key stays unique.
The human-readable prompt version goes in the variant name so chart legends stay readable.
Splits are integers summing to 100; the last variant absorbs any remainder.
"""
n = len(versions)
base = 100 // n
splits = [base] * n
splits[-1] += 100 - base * n
variants: list[dict[str, Any]] = []
for i, (version, split) in enumerate(zip(versions, splits)):
if i == 0:
key = "control"
elif n == 2:
key = "test"
else:
key = f"test-{i}"
variants.append({"key": key, "name": f"v{version}", "rollout_percentage": split})
return variants
def _slugify_feature_flag_key(name: str, *, team_id: int) -> str:
"""Slugify a feature flag name, adding a numeric suffix if the slug already exists for this team."""
base = slugify(name)[:200] or "experiment"
candidate = base
suffix = 2
while FeatureFlag.objects.filter(team_id=team_id, key=candidate).exists():
candidate = f"{base}-{suffix}"
suffix += 1
return candidate
def _accessible_session_ids(
request: Request, user_access_control: UserAccessControl, team: Team, session_ids: list[str]
) -> list[str]:
"""Drop session ids whose recording the viewer is denied at the object level.
The resource-level `session_recording` check the session-context actions run first grants
access to the replay product, not to every recording in it: a recording can carry its own
access controls, which the replay retrieve endpoint enforces via `check_object_permissions`.
Without this filter a viewer denied one recording could still read which experiments it saw.
Object-level controls can only target a recording that has a Postgres row, so an id without
one is returned as accessible. That matches replay, which serves those ids from an unsaved
`SessionRecording` no access control row can point at.
"""
if is_service_auth(request):
# Mirrors AccessControlPermission.has_object_permission: service credentials authenticate
# as synthetic users that UserAccessControl cannot evaluate, so they are gated by API
# scope and project membership instead of object-level RBAC.
return session_ids
recordings = SessionRecording.objects.filter(team=team, session_id__in=session_ids)
denied_ids = {
recording.session_id
for recording in recordings
if not user_access_control.check_access_level_for_object(recording, required_level="viewer")
}
return [session_id for session_id in session_ids if session_id not in denied_ids]
# Query parameters shared by the list endpoint and matching_ids, which accepts the same filters.
EXPERIMENT_LIST_FILTER_PARAMETERS = [
OpenApiParameter(
name="status",
location=OpenApiParameter.QUERY,
type=str,
enum=["draft", "running", "paused", "exposure_frozen", "stopped", "complete", "all"],
description=(
'Filter by experiment status. "running", "paused", and "exposure_frozen" are mutually exclusive: '
'"running" returns launched experiments with an active feature flag, "paused" returns launched '
'experiments whose feature flag is deactivated, and "exposure_frozen" returns launched '
"experiments whose exposure was frozen to the already-enrolled cohort while metrics keep "
'flowing. "complete" is an alias for "stopped". "all" disables status filtering.'
),
required=False,
),
OpenApiParameter(
name="archived",
location=OpenApiParameter.QUERY,
type=bool,
description="Filter by archived state. Defaults to non-archived experiments only.",
required=False,
),
OpenApiParameter(
name="feature_flag_id",
location=OpenApiParameter.QUERY,
type=int,
description="Filter to experiments linked to the given feature flag ID.",
required=False,
),
OpenApiParameter(
name="created_by_id",
location=OpenApiParameter.QUERY,
type=str,
description=(
"Filter to experiments created by the given user(s). Accepts a single user ID, "
"or a JSON-encoded / comma-separated list of user IDs to match any of them."
),
required=False,
),
OpenApiParameter(
name="search",
location=OpenApiParameter.QUERY,
type=str,
description="Free-text search applied to the experiment name and its feature flag key (case-insensitive).",
required=False,
),
OpenApiParameter(
name="prompt_name",
location=OpenApiParameter.QUERY,
type=str,
description=(
"Filter to experiments created from an LLM prompt with this name. "
"Matches experiments whose parameters.prompt_metadata.name equals the given value."
),
required=False,
),
OpenApiParameter(
name="event",
location=OpenApiParameter.QUERY,
type=str,
description=(
"Filter to experiments whose metrics reference this event name. Matches events used "
"directly in metric queries as well as events behind any actions those metrics reference."
),
required=False,
),
OpenApiParameter(
name="order",
location=OpenApiParameter.QUERY,
type=str,
description=(
"Field to order by. Prefix with '-' for descending. Allowlisted fields include name, "
"created_at, updated_at, start_date, end_date, duration, and status."
),
required=False,
),
OpenApiParameter(
name="tags",
location=OpenApiParameter.QUERY,
type=str,
description=(
"JSON-encoded list of tag names. Returns experiments carrying at least one of the "
'given tags, e.g. `["growth", "checkout"]`.'
),
required=False,
),
OpenApiParameter(
name="excluded_tags",
location=OpenApiParameter.QUERY,
type=str,
description=(
"JSON-encoded list of tag names. Excludes experiments carrying any of the given tags, "
"even when they also carry non-excluded tags."
),
required=False,
),
]
class ExperimentBurstRateThrottle(PersonalOrProjectSecretApiKeyRateThrottle):
# Same scope and rate as the default BurstRateThrottle so personal-key and session
# behavior is unchanged; the subclass only adds per-key throttling for PSAK requests,
# which the default throttles silently bypass (no personal key, no throttling).
scope = "burst"
rate = "480/minute"
class ExperimentSustainedRateThrottle(PersonalOrProjectSecretApiKeyRateThrottle):
scope = "sustained"
rate = "4800/hour"
class ExperimentProjectSecretApiKeyTeamBurstThrottle(ProjectSecretApiKeyTeamRateThrottle):
"""Per-team aggregate burst budget across all of a project's PSAKs — same size as the
per-key budget, so minting extra keys never multiplies a project's total burst capacity."""
scope = "experiment_psak_team_burst"
rate = "480/minute"
class ExperimentProjectSecretApiKeyTeamSustainedThrottle(ProjectSecretApiKeyTeamRateThrottle):
"""Per-team aggregate sustained budget across all of a project's PSAKs."""
scope = "experiment_psak_team_sustained"
rate = "4800/hour"
@extend_schema_view(
# PATCH /experiments/{id}/
# DRF mixin calls implementation at ExperimentSerializer.update
# request=ExperimentWriteSerializer is schema-only: it adds the writable feature_flag input
# to the OpenAPI request body; runtime validation stays on ExperimentSerializer.
partial_update=extend_schema(
description="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.",
request=ExperimentWriteSerializer,
),
# PUT /experiments/{id}/, same request shape as PATCH
update=extend_schema(request=ExperimentWriteSerializer),
# POST /experiments/ — DRF mixin calls ExperimentSerializer.create
create=extend_schema(
description="Create a new experiment in draft status with optional metrics.",
request=ExperimentWriteSerializer,
),
# GET /experiments/{id}/ — DRF mixin, read-only serialization via ExperimentSerializer
retrieve=extend_schema(
description="Retrieve a single experiment by ID, including its current status, metrics, feature flag, and results metadata.",
),
# GET /experiments/ — DRF mixin, filtering via ExperimentService.filter_experiments_queryset
list=extend_schema(
description="List experiments for the current project. Supports filtering by status and archival state.",
parameters=EXPERIMENT_LIST_FILTER_PARAMETERS,
),
# DELETE /experiments/{id}/
# Logic and API docs defined in posthog/api/forbid_destroy_model.py (hard delete not allowed)
)
class EnterpriseExperimentsViewSet(
# ApprovalHandlingMixin converts ApprovalRequired exceptions (raised by
# FeatureFlagSerializer in ship_variant) into 409 HTTP responses. The
# approval check itself lives in the service layer — this mixin is only
# responsible for exception-to-response formatting.
ApprovalHandlingMixin,
ForbidDestroyModel,
TeamAndOrgViewSetMixin,
AccessControlViewSetMixin,
TaggedItemViewSetMixin,
viewsets.ModelViewSet,
):
scope_object: Literal["experiment"] = "experiment"
# bulk_update_tags comes from TaggedItemViewSetMixin and must be opted into PAT access explicitly.
scope_object_write_actions = ["create", "update", "partial_update", "patch", "destroy", "bulk_update_tags"]
bulk_tag_activity_scope = "Experiment"
# Extends the default authenticators (TeamAndOrgViewSetMixin appends session/PAT/OAuth).
authentication_classes = [ProjectSecretAPIKeyAuthentication]
# A project secret API key with experiment:read can export experiment definitions
# (list/retrieve) — a service credential not tied to one person's account. Everything
# else (writes, lifecycle actions, results) stays session/PAT/OAuth-only.
psak_allowed_actions = ["list", "retrieve"]
throttle_classes = [
ExperimentBurstRateThrottle,
ExperimentSustainedRateThrottle,
ExperimentProjectSecretApiKeyTeamBurstThrottle,
ExperimentProjectSecretApiKeyTeamSustainedThrottle,
]
serializer_class = ExperimentSerializer
queryset = (
Experiment.objects.select_related(
"team",
"feature_flag",
"created_by",
"exposure_cohort",
"holdout__created_by",
)
.prefetch_related(
flag_evaluation_contexts_prefetch(),
Prefetch(
# order_by("id") keeps saved metrics in insertion order — select_related below adds
# joins that would otherwise leave the row order unspecified.
"experimenttosavedmetric_set",
queryset=ExperimentToSavedMetric.objects.select_related("saved_metric", "experiment__team").order_by(
"id"
),
),
)
.all()
)
ordering = "-created_at"
def get_serializer_class(self):
# The list view renders only scalar/flag fields; use the lightweight serializer so the
# heavy metric fields (and their prefetch/fingerprinting) are skipped — see safely_get_queryset.
if self.action == "list":
return ExperimentBasicSerializer
return ExperimentSerializer
def update(self, request: Request, *args: Any, **kwargs: Any) -> Response:
if is_scout_sandbox_request(request) and isinstance(request.data, Mapping):
self._check_scout_update(request)
# Structured 409 body ({detail, current_version, conflicting_*}) so clients can refetch
# and retry precisely; the default exception handler would flatten it to a plain string.
try:
return super().update(request, *args, **kwargs)
except ExperimentVersionConflict as err:
return Response(err.response_data(), status=err.status_code)
def _check_scout_update(self, request: Request) -> None:
# The API has no hard delete, so `deleted: true` on an update is the delete a scout must not make.
if is_true(request.data.get("deleted", False)):
refuse_scout_experiment_delete(True)
if update_carries_flag_config(
request.data, legacy_flag_config_keys=ExperimentService.FEATURE_FLAG_CONFIG_KEYS
) and not self._token_can_write_feature_flag(request):
experiment: Experiment = self.get_object()
refuse_scout_live_flag_config_change(
True,
can_write_feature_flag=False,
flag_is_live=not experiment.is_draft
or (experiment.feature_flag is not None and experiment.feature_flag.active),
)
@tracer.start_as_current_span("ExperimentViewSet.list")
def list(self, request: Request, *args: Any, **kwargs: Any) -> Response:
return super().list(request, *args, **kwargs)
@tracer.start_as_current_span("ExperimentViewSet.safely_get_queryset")
def safely_get_queryset(self, queryset) -> QuerySet:
request = getattr(self, "request", None)
if self.action == "bulk_update_tags":
# The bulk tag mutation reads only id/team_id/name and the tags themselves (which the
# mixin prefetches). Drop the detail joins and heavy JSON columns so selecting up to
# 500 experiments doesn't drag every metrics/filters payload along.
queryset = (
queryset.select_related(None)
.prefetch_related(None)
.select_related("created_by")
.defer(*LIST_DEFERRED_FIELDS)
)
if self.action in ("health", "health_inputs", "in_session_exposure"):
# The facade reads the experiment again with the joins its checks need, so the object lookup
# here only checks access.
queryset = queryset.select_related(None).prefetch_related(None).select_related("team")
if self.action == "list":
# ExperimentBasicSerializer omits metrics/saved_metrics, so drop the saved-metric
# prefetch and defer the heavy JSON columns. The ?event= filter reads metrics via its
# own values_list/queries, so it is unaffected by the defer. is_legacy is computed in
# SQL (see list_is_legacy_annotation) so the badge/guards survive without loading metrics.
queryset = (
queryset.prefetch_related(None)
.prefetch_related(flag_evaluation_contexts_prefetch())
.defer(*LIST_DEFERRED_FIELDS)
.annotate(is_legacy_annotation=list_is_legacy_annotation())
)
service = ExperimentService(team=self.team, user=getattr(request, "user", None))
return service.filter_experiments_queryset(
queryset,
action=self.action,
query_params=getattr(request, "query_params", None),
request_data=getattr(request, "data", None),
)
@extend_schema(
responses={200: ExperimentMatchingIdsResponseSerializer},
parameters=EXPERIMENT_LIST_FILTER_PARAMETERS,
)
@action(methods=["GET"], detail=False, pagination_class=None, required_scopes=["experiment:read"])
def matching_ids(self, request: Request, *args: Any, **kwargs: Any) -> Response:
"""
Get IDs of all experiments matching the current list filters.
Accepts the same query params as the list endpoint and returns only
IDs of experiments the user has permission to edit.
"""
service = ExperimentService(team=self.team, user=request.user)
queryset = service.filter_experiments_queryset(
self.get_queryset(),
action="list",
query_params=request.query_params,
)
# Drop the class queryset's joins/prefetches; the access check below reads only the
# experiment ID and its creator, so load exactly those (a bare only("id") would leave
# created_by deferred and cost two refresh queries per row).
queryset = (
queryset.select_related(None).prefetch_related(None).select_related("created_by").only("id", "created_by")
)
if not self.user_access_control:
editable_ids = list(queryset.values_list("id", flat=True))
else:
experiments = list(queryset)
self.user_access_control.preload_object_access_controls(cast(list, experiments))
editable_ids = [
experiment.id
for experiment in experiments
if (user_access_level := self.user_access_control.get_user_access_level(experiment))
and access_level_satisfied_for_resource("experiment", user_access_level, "editor")
]
return Response(ExperimentMatchingIdsResponseSerializer({"ids": editable_ids, "total": len(editable_ids)}).data)
def dangerously_get_required_scopes(self, request: Request, view: Any) -> RequiredScopes | None:
# Archiving with disable_feature_flag=true also disables and archives the linked flag,
# which is a feature_flag write — require feature_flag:write on the token, not just
# experiment:write. Other actions fall back to their own scopes.
if self.action == "archive":
scopes = ["experiment:write"]
# Use DRF's own truthy set so this matches how ArchiveExperimentSerializer parses the field.
if request.data.get("disable_feature_flag", False) in serializers.BooleanField.TRUE_VALUES:
scopes.append("feature_flag:write")
return scopes
# Ending or shipping with open_cleanup_pr=true starts a Desktop task that opens a pull
# request. Starting a task is a task write, so require task:write on the token, not
# just experiment:write.
if self.action in ("end", "ship_variant"):
scopes = ["experiment:write"]
if request.data.get("open_cleanup_pr", False) in serializers.BooleanField.TRUE_VALUES:
scopes.append("task:write")
# Saving the team default cleanup repository writes environment-wide configuration,
# so the token also needs project:write, matching the experiments_config surface.
if request.data.get("set_repository_as_team_default", False) in serializers.BooleanField.TRUE_VALUES:
scopes.append("project:write")
return scopes
return None
def _check_team_default_repository_access(self, request: Request) -> None:
"""The team default cleanup repository is environment-wide configuration; writing it via
experiments_config requires project admin (TeamMemberStrictManagementPermission), so the
write through end/ship_variant must hold the same bar."""
user_permissions = UserPermissions(user=cast(User, request.user))
effective_level = user_permissions.team(self.team).effective_membership_level
if effective_level is None or effective_level < OrganizationMembership.Level.ADMIN:
raise PermissionDenied("Setting the default cleanup repository requires project admin access.")
def _check_copy_target_access(self, request: Request, target_team: Team) -> None:
"""Authorize the target project of a cross-project copy.
Every class in the permission stack resolves against `view.team`, which is the source
project in the URL, so the target project is not checked at all by the time the action
body runs. This applies the same gates the target project's own `POST /experiments/`
would apply: the credential's project scope, project membership, and experiment editor
access in the target.
"""
scoped_teams = get_authenticator_scoped_team_ids(getattr(request, "successful_authenticator", None))
if scoped_teams is not None and target_team.id not in scoped_teams:
raise PermissionDenied(f"API key does not have access to the requested project: ID {target_team.id}.")
user = cast(User, request.user)
effective_level = UserPermissions(user=user).team(target_team).effective_membership_level
if effective_level is None or effective_level < OrganizationMembership.Level.MEMBER:
raise PermissionDenied("You do not have write access to the target project.")
target_access_control = UserAccessControl(user=user, team=target_team)
if not target_access_control.check_access_level_for_object(
target_team, required_level="member"
) or not target_access_control.check_access_level_for_resource("experiment", required_level="editor"):
raise PermissionDenied("You do not have permission to create experiments in the target project.")
def _token_can_write_feature_flag(self, request: Request) -> bool:
"""Whether the request's token carries feature_flag:write.
Archiving/unarchiving an experiment can touch the linked flag's archived/active
state as a side effect; that is a feature_flag write and must not be reachable with
only experiment:write. Session and other non-token auth aren't scope-limited (gated by
access control instead), mirroring APIScopePermission.
"""
scopes = get_authenticator_scopes(request.successful_authenticator)
if scopes is None:
return True
return "*" in scopes or "feature_flag:write" in scopes
@extend_schema(
request=None,
responses=ExperimentSerializer,
)
@action(methods=["POST"], detail=True, required_scopes=["experiment:write"])
def launch(self, request: Request, *args: Any, **kwargs: Any) -> Response:
"""
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).
"""
experiment: Experiment = self.get_object()
service = ExperimentService(team=self.team, user=request.user)
launched_experiment = service.launch_experiment(experiment, request=request)
return Response(ExperimentSerializer(launched_experiment, context=self.get_serializer_context()).data)
@extend_schema(
request=ArchiveExperimentSerializer,
responses=ExperimentSerializer,
)
# required_scopes is computed by dangerously_get_required_scopes — disabling the linked
# flag additionally requires feature_flag:write.
@action(methods=["POST"], detail=True)
def archive(self, request: Request, *args: Any, **kwargs: Any) -> Response:
"""
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.
"""
experiment: Experiment = self.get_object()
request_serializer = ArchiveExperimentSerializer(data=request.data)
request_serializer.is_valid(raise_exception=True)
service = ExperimentService(team=self.team, user=request.user)
archived_experiment = service.archive_experiment(
experiment,
disable_feature_flag=request_serializer.validated_data["disable_feature_flag"],
can_write_feature_flag=self._token_can_write_feature_flag(request),
request=request,
)
return Response(ExperimentSerializer(archived_experiment, context=self.get_serializer_context()).data)
@extend_schema(
request=None,
responses=ExperimentSerializer,
)
@action(methods=["POST"], detail=True, required_scopes=["experiment:write"])
def unarchive(self, request: Request, *args: Any, **kwargs: Any) -> Response:
"""
Unarchive an archived experiment.
Restores the experiment to the default list view. Returns 400 if the
experiment is not currently archived.
"""
experiment: Experiment = self.get_object()
service = ExperimentService(team=self.team, user=request.user)
unarchived_experiment = service.unarchive_experiment(
experiment,
can_write_feature_flag=self._token_can_write_feature_flag(request),
request=request,
)
return Response(ExperimentSerializer(unarchived_experiment, context=self.get_serializer_context()).data)
@extend_schema(
request=EndExperimentSerializer,
responses=ExperimentSerializer,
)
# required_scopes is computed by dangerously_get_required_scopes; opening a cleanup PR
# additionally requires task:write.
@action(methods=["POST"], detail=True)
def end(self, request: Request, *args: Any, **kwargs: Any) -> Response:
"""
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.
"""
experiment: Experiment = self.get_object()
request_serializer = EndExperimentSerializer(data=request.data)
request_serializer.is_valid(raise_exception=True)
refuse_scout_cleanup_pr(
is_scout_sandbox_request(request), open_cleanup_pr=request_serializer.validated_data["open_cleanup_pr"]
)
if request_serializer.validated_data["set_repository_as_team_default"]:
self._check_team_default_repository_access(request)
service = ExperimentService(team=self.team, user=request.user)
ended_experiment = service.end_experiment(
experiment,
conclusion=request_serializer.validated_data.get("conclusion"),
conclusion_comment=request_serializer.validated_data.get("conclusion_comment"),
open_cleanup_pr=request_serializer.validated_data["open_cleanup_pr"],
repository=request_serializer.validated_data.get("repository"),
set_repository_as_team_default=request_serializer.validated_data["set_repository_as_team_default"],
request=request,
)
return Response(ExperimentSerializer(ended_experiment, context=self.get_serializer_context()).data)
@extend_schema(
request=ShipVariantSerializer,
responses=ExperimentSerializer,
)
# required_scopes is computed by dangerously_get_required_scopes; opening a cleanup PR
# additionally requires task:write.
@action(methods=["POST"], detail=True, url_path="ship_variant")
def ship_variant(self, request: Request, *args: Any, **kwargs: Any) -> Response:
"""
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.
"""
refuse_scout_ship_variant_without_flag_write(
is_scout_sandbox_request(request), can_write_feature_flag=self._token_can_write_feature_flag(request)
)
experiment: Experiment = self.get_object()
request_serializer = ShipVariantSerializer(data=request.data)
request_serializer.is_valid(raise_exception=True)
refuse_scout_cleanup_pr(
is_scout_sandbox_request(request), open_cleanup_pr=request_serializer.validated_data["open_cleanup_pr"]
)
if request_serializer.validated_data["set_repository_as_team_default"]:
self._check_team_default_repository_access(request)
service = ExperimentService(team=self.team, user=request.user)
shipped_experiment = service.ship_variant(
experiment,
variant_key=request_serializer.validated_data["variant_key"],
release_to_everyone=request_serializer.validated_data["release_to_everyone"],
conclusion=request_serializer.validated_data.get("conclusion"),
conclusion_comment=request_serializer.validated_data.get("conclusion_comment"),
open_cleanup_pr=request_serializer.validated_data["open_cleanup_pr"],
repository=request_serializer.validated_data.get("repository"),
set_repository_as_team_default=request_serializer.validated_data["set_repository_as_team_default"],
request=request,
)
return Response(ExperimentSerializer(shipped_experiment, context=self.get_serializer_context()).data)
@extend_schema(
request=None,
responses=ExperimentFlagCleanupTaskSerializer,
)
@action(methods=["GET"], detail=True, required_scopes=["experiment:read"])
def flag_cleanup_task(self, request: Request, *args: Any, **kwargs: Any) -> Response:
"""
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.
"""
experiment: Experiment = self.get_object()
if not experiment.flag_cleanup_task_id:
raise NotFound("No flag cleanup task was opened for this experiment.")
# Read through the facade rather than the tasks API: cleanup tasks are creator-visible
# there, but their status should be visible to everyone who can see the experiment.
run = tasks_facade.get_latest_run_by_task([experiment.flag_cleanup_task_id]).get(
str(experiment.flag_cleanup_task_id)
)
# get_latest_run_by_task filters by task id only. After a project transfer the
# experiment can point at a task in the old team — treat that run as absent rather
# than leaking its status across teams.
if run is not None and run.team_id != experiment.team_id:
run = None
# The PR URL comes from the task run's output blob — only pass it through when it
# actually points at GitHub, since the frontend renders it as a GitHub link.
pr_url = run.pr_url if run else None
if pr_url and not pr_url.startswith("https://github.com/"):
pr_url = None
response_serializer = ExperimentFlagCleanupTaskSerializer(
{
"task_id": experiment.flag_cleanup_task_id,
"run_status": run.status if run else "queued",
"is_terminal": run.is_terminal if run else False,
"pr_url": pr_url,
# Whether the tasks API would let this user open the task page — cleanup
# tasks are creator-visible there today, so hide the link from everyone else.
"can_view_task": tasks_facade.task_visible(
experiment.flag_cleanup_task_id, self.team.pk, cast(User, request.user).id
),
}
)
return Response(response_serializer.data)
@extend_schema(
request=None,
responses=ExperimentFlagCleanupTargetSerializer,
)
@action(methods=["GET"], detail=True, url_path="flag_cleanup_target", required_scopes=["experiment:read"])
def flag_cleanup_target(self, request: Request, *args: Any, **kwargs: Any) -> Response:
"""
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.
"""
experiment: Experiment = self.get_object()
service = ExperimentService(team=self.team, user=request.user)
target = service.get_cleanup_repository_target(experiment)
return Response(ExperimentFlagCleanupTargetSerializer(target).data)
@extend_schema(
request=None,
responses=ExperimentHealthSerializer,
)
@action(methods=["GET"], detail=True, required_scopes=["experiment:read"])
def health(self, request: Request, *args: Any, **kwargs: Any) -> Response:
"""
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. `checks` gives the result of
each check, so a check that found no problem can be told from one that did not apply or could
not read an input.
The checks here read the experiment, its flag, its linked metrics, the project's event and
property definitions, the cohorts of the exposure criteria, 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
`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.
Two checks read whether the project received an event from its event definitions: a
definition without `last_seen_at`, such as one Wizard wrote for a planned event, counts as
not received. A name whose definition was deleted since launch, or in the last day for a
draft, is not checked, because ingestion writes the definition again only when the event
arrives. No missing definition is checked when ingestion saw none of the experiment's events
in the last day, because ingestion can be set to skip a team. `metric_event_not_ingested`
names each metric that
reads an event the project never received, in the `evidence` keys `metric_N`,
`metric_N_role` and `metric_N_events`. `exposure_criteria_cannot_match` reports a custom
exposure event the project never received (`exposure_event_not_ingested`), a
`$feature_flag` filter on the flag call events that requires another flag
(`filter_on_another_flag`), and a filter on an event or person property that the project has
no definition of, with an operator that a missing property fails
(`filter_on_property_not_ingested`, the keys in `evidence.properties`). A property whose
definition was ever deleted is not checked, and neither is an event property filter on an
action or on `$groupidentify`, whose properties ingestion keeps no definitions of. An event
or property not received is info before launch, in the first 24 hours after launch, and when
only secondary metrics read it, and a warning otherwise. `filter_on_another_flag` is a
warning in every state, `filter_on_property_not_ingested` also reports after the end, and
the other findings stop at the end.
`exposure_filters` reads the cohort filters of the exposure criteria and of the activation,
not the test account filters. `exposure_filter_on_dynamic_cohort` is a warning in every
state: the results use the members of a dynamic cohort at the calculation, not at exposure.
Its subcode is `cohort_forces_variant` when a release condition of the flag that matches the
cohort's members gives one variant, `cohort_in_release_conditions` when the release
conditions match its members otherwise, and `evidence.cohort_ids` names the cohorts. Both
subcodes need the exposure criteria to keep the members too, not to leave them out.
`metric_cannot_compile` builds and compiles the query of each metric without running it, as
the caller, so a metric that every calculation fails on shows before launch. A metric that
reads a warehouse table or view the caller may not query is not checked for them. The finding
names each failing metric in the `evidence` keys `metric_N`, `metric_N_role`, `metric_N_error`
(the error class, which is also the subcode of the first metric) and `metric_N_message` (the
compiler's message). It is a warning when a primary metric fails, also after the end, because
the calculation after the fix reads the events up to the end. It is info otherwise. A failure
inside ClickHouse, such as a type that the data holds, isn't found. A failing metric compiles
again on every request. A metric that compiles is cached per caller for a day, so a cohort or
table that is deleted after a compile can take up to a day to show.
`metric_calculation_failed` reports each metric whose latest calculation failed, from the
latest finished calculation that the results page shows. It leaves out a metric that
`metric_cannot_compile` reports. The subcode is the kind of the first failure: `busy`,
`query_limit` (the query reached the read, memory, time or length limit), `settings` (a setting of
the metric or the experiment), `not_enough_data`, `experiment_too_old` (the experiment
started too long ago to calculate again) or `unexpected_error`. Each metric is in the
`evidence` keys `metric_N`, `metric_N_role`, `metric_N_failure` (the kind), `metric_N_error`
(the limit, or the family of a setting) and `metric_N_message` (only a message that PostHog
wrote for users), and `calculated_at` is when the calculation finished. It is a
warning when a primary metric fails for a kind that a change fixes (`query_limit`,
`settings`, `experiment_too_old`), also after the end, because the calculation after the fix
reads the events up to the end. It is info otherwise. When the first failure reached the
read, memory or time limit, `reason` names the cause that the calculation shows: `metric`
when another metric of the same calculation completed the same read of the exposures, or
`exposure_criteria` when every metric reached a limit and an exposure or test account filter
makes each query read all the properties of an event, person or group. `evidence.properties`
then names the filters. A query that read precomputed exposures doesn't apply those filters,
so it can't get `exposure_criteria`. It is null otherwise.
`metric_all_zero` reports a metric that reads zero in every variant, from the same latest
finished calculation, so the results page shows "Not enough data yet" at any sample size.
Each side of a ratio that is zero in every variant counts on its own. It reads the stored
result and the project's event definitions, and no events. A primary metric needs 1,000
exposures in the result and 72 hours of data, because most zeros before that are outcomes
that take time. A retention metric counts those hours from the start of its retention
window. The subcode is the cause of the first metric: `blank_event` (an event with an empty
name), `event_stopped` (the project last received the event before launch, while ingestion
still records the project), `outlier_bound` (an upper outlier bound that is 0 while some
exposures have a value) or null when none shows a cause. `blank_event` and `outlier_bound`
also report a secondary metric, and need only 100 exposures and 12 hours of data, because
they read 0 at any traffic. A bound on the largest value of the exposures can't be 0 while
one has a value, so it is no cause. Neither is a bound on a metric with breakdowns, which
gets one bound per breakdown group. Until the end, the check leaves out a metric that uses an
event `metric_event_not_ingested` reports. Each metric, or side of a ratio, is in the
`evidence` keys `metric_N`, `metric_N_role`, `metric_N_side`, `metric_N_exposures` and
`metric_N_cause`. It is a warning for a primary metric. After the end it stays a warning only
for a cause that a setting fixes, because the calculation after the fix reads the events up
to the end. It is info otherwise.
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 `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`. When none of them includes
everyone, so that every other user gets no variant, `closed_to_matched_users` replaces it,
as a warning. A condition without filters, or with only filters that leave users out,
includes everyone.
A draft whose flag has no recorded call gets the info `new_flag_no_traffic`. The record
is the flag's `last_called_at`, which a periodic task updates, so it trails a call. The
check reports `not_checked` when the organization's flag calls skip the events table,
and when the project has no active flag, because the web SDK then requests no flags.
A running experiment whose flag is disabled gets `paused_from_experiment`, as info, when
its latest pause or resume since launch is a pause of the experiment. Otherwise it gets
`running_but_flag_disabled`, as a warning. A caller who can't view the linked flag's
history gets the warning, because the pause is not read. A draft whose flag is already
active with multiple variants gets `not_started_but_multiple_variants_rolled_out` as info.
An ended experiment whose flag is still active with multiple variants gets no finding when
another experiment on the flag is running or launched after the end. Otherwise it gets
`ended_flag_shared_with_draft` as info when a draft experiment uses the flag,
`ended_but_multiple_variants_rolled_out` as a warning when the flag's `last_called_at` is
after the end and within the last 3 days, and `ended_flag_not_called` as info when it is
not, from 3 days and an hour after the end, because `last_called_at` trails a call. Until
then without such a call, or when the organization's flag calls can't be read, it gets
`ended_flag_calls_unknown` as info.
A running experiment whose first primary metric is a funnel gets the info
`early_significance` (subcode `below_detectable_effect`) when a significant variant's
difference is smaller than the smallest difference its sample can detect, while that
sample is below the one the running time estimate plans for the minimum detectable
effect. It reads the metric's current stored result, the one the results page shows
after its last calculation, and the running time calculator's formula.
A running experiment with `only_count_matured_users` on gets the info
`metrics_not_matured` while it is younger than the conversion or retention window of
every primary metric, because no user can count for those metrics until a window passes.
"""
experiment: Experiment = self.get_object()
health = get_experiment_health(
team_id=self.team_id,
experiment_id=experiment.id,
reader_access=self._health_reader_access(request, experiment),
user=request.user if isinstance(request.user, User) else None,
)
return Response(ExperimentHealthSerializer(health).data)
@extend_schema(
request=None,
responses=ExperimentHealthInputsSerializer,
)
@action(
methods=["GET"],
detail=True,
required_scopes=["experiment:read"],
throttle_classes=[ClickHouseBurstRateThrottle, ClickHouseSustainedRateThrottle],
)
def health_inputs(self, request: Request, *args: Any, **kwargs: Any) -> Response:
"""
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.
"""
if not (request.user.is_staff or settings.DEBUG or is_impersonated_session(request)):
raise PermissionDenied("Only staff users can read the health check inputs.")
experiment: Experiment = self.get_object()
inputs = get_experiment_health_inputs(
team_id=self.team_id,
experiment_id=experiment.id,
reader_access=self._health_reader_access(request, experiment),
user=cast(User, request.user),
)
return Response(ExperimentHealthInputsSerializer(inputs).data)
def _health_reader_access(self, request: Request, experiment: Experiment) -> ExperimentHealthReaderAccess:
# The split history is flag history, which `activity` keeps behind the flag's own access controls and
# `activity_log:read`. It also queries events, which a scoped token reaches only with `query:read`.
scopes = get_authenticator_scopes(request.successful_authenticator)
missing_scopes = (
set()
if scopes is None or "*" in scopes
else set(scopes_not_covered(scopes, ["activity_log:read", "query:read"]))
)
can_view_flag = experiment.feature_flag_id is None or self.user_access_control.check_access_level_for_object(
experiment.feature_flag, required_level="viewer"
)
restrictions = get_restricted_properties_with_group_type_index_for_team(
user=cast(User, request.user), team_id=self.team_id
)
return ExperimentHealthReaderAccess(
can_read_flag_history=bool(can_view_flag) and "activity_log:read" not in missing_scopes,
can_query_events="query:read" not in missing_scopes,
denied_event_properties=split_restricted_property_names(restrictions).event,
)
@validated_request(
query_serializer=ExperimentActivityQuerySerializer,
responses={
200: OpenApiResponse(response=ActivityLogPaginatedResponseSerializer),
404: OpenApiResponse(response=None),
},
)
@action(methods=["GET"], detail=True, required_scopes=["activity_log:read"])
def activity(self, request: ValidatedRequest, *args: Any, **kwargs: Any) -> Response:
"""
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.
"""
limit = request.validated_query_data["limit"]
page = request.validated_query_data["page"]
experiment: Experiment = self.get_object()
# Holdout and shared-metric changes log under the Experiment scope with the child
# object's own id, so they need their own type-matched clauses. The experiment's own
# clause must exclude those detail types in turn: an unrelated holdout or shared
# metric whose pk collides with this experiment's id would otherwise leak in.
# The linked flag's changes log under the FeatureFlag scope, so each clause carries
# its own scope instead of a single outer scope filter.
activity_filter = Q(scope="Experiment", item_id=str(experiment.id)) & ~Q(
detail__type__in=["holdout", "shared_metric"]
)
if experiment.holdout_id is not None:
activity_filter |= Q(scope="Experiment", item_id=str(experiment.holdout_id), detail__type="holdout")
saved_metric_ids = [str(pk) for pk in experiment.saved_metrics.values_list("id", flat=True)]
if saved_metric_ids:
activity_filter |= Q(scope="Experiment", item_id__in=saved_metric_ids, detail__type="shared_metric")
# The flag's history stays behind the flag's own access controls: a viewer of the
# experiment may have "none" access to the linked flag.
if experiment.feature_flag_id is not None and self.user_access_control.check_access_level_for_object(
experiment.feature_flag, required_level="viewer"
):
activity_filter |= Q(scope="FeatureFlag", item_id=str(experiment.feature_flag_id))
activity_query = (
ActivityLog.objects.select_related("user")
.filter(activity_filter, team_id=self.team_id)
.order_by("-created_at")
)
activity_page = get_activity_page(activity_query, limit, page)
return activity_page_response(activity_page, limit, page, request)
@extend_schema(
request=None,
responses=ExperimentSerializer,
)
@action(methods=["POST"], detail=True, required_scopes=["experiment:write"])
def pause(self, request: Request, *args: Any, **kwargs: Any) -> Response:
"""
Pause a running experiment.
Deactivates the linked feature flag so it is no longer returned by the
/decide endpoint. Users fall back to the application default (typically
the control experience), and no new exposure events are recorded (i.e.
$feature_flag_called is not fired).
Returns 400 if the experiment is not running or is already paused.
"""
experiment: Experiment = self.get_object()
service = ExperimentService(team=self.team, user=request.user)
paused_experiment = service.pause_experiment(experiment, request=request)
return Response(ExperimentSerializer(paused_experiment, context=self.get_serializer_context()).data)
@extend_schema(
request=None,
responses=ExperimentSerializer,
)
@action(methods=["POST"], detail=True, required_scopes=["experiment:write"])
def resume(self, request: Request, *args: Any, **kwargs: Any) -> Response:
"""
Resume a paused experiment.
Reactivates the linked feature flag so it is returned by /decide again.
Users are re-bucketed deterministically into the same variants they had
before the pause, and exposure tracking resumes.
Returns 400 if the experiment is not running or is not paused.
"""
experiment: Experiment = self.get_object()
service = ExperimentService(team=self.team, user=request.user)
resumed_experiment = service.resume_experiment(experiment, request=request)
return Response(ExperimentSerializer(resumed_experiment, context=self.get_serializer_context()).data)
@extend_schema(
request=None,
responses=ExperimentSerializer,
)
@action(methods=["POST"], detail=True, required_scopes=["experiment:write"])
def freeze_exposure(self, request: Request, *args: Any, **kwargs: Any) -> Response:
"""
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.
"""
experiment: Experiment = self.get_object()
service = ExperimentService(team=self.team, user=request.user)
frozen_experiment = service.freeze_exposure(experiment, request=request)
return Response(ExperimentSerializer(frozen_experiment, context=self.get_serializer_context()).data)
@extend_schema(
request=None,
responses=ExperimentSerializer,
)
@action(methods=["POST"], detail=True, required_scopes=["experiment:write"])
def unfreeze_exposure(self, request: Request, *args: Any, **kwargs: Any) -> Response:
"""
Reopen enrollment on an exposure-frozen experiment.
Removes the snapshot-cohort condition and freeze markers from every release
group, restoring the flag's original targeting: new users can enroll again
and already-enrolled users keep their assigned variant. The snapshot cohort
is soft-deleted. The serialized status returns to 'running'.
Returns 400 if the experiment is not running or its exposure is not frozen.
"""
experiment: Experiment = self.get_object()
service = ExperimentService(team=self.team, user=request.user)
unfrozen_experiment = service.unfreeze_exposure(experiment, request=request)
return Response(ExperimentSerializer(unfrozen_experiment, context=self.get_serializer_context()).data)
@extend_schema(
request=None,
responses=ExperimentSerializer,
)
@action(methods=["POST"], detail=True, required_scopes=["experiment:write"])
def reset(self, request: Request, *args: Any, **kwargs: Any) -> Response:
"""
Reset an experiment back to draft state.
Clears start/end dates, conclusion, archived flag, and any flag-cleanup
task pointer. The feature flag is left unchanged — users continue to see
their assigned variants.
Previously collected events still exist but won't be included in
results unless the start date is manually adjusted after re-launch.
Returns 400 if the experiment is already in draft state.
"""
experiment: Experiment = self.get_object()
service = ExperimentService(team=self.team, user=request.user)
reset_experiment = service.reset_experiment(experiment, request=request)
return Response(ExperimentSerializer(reset_experiment, context=self.get_serializer_context()).data)
@action(methods=["POST"], detail=True, required_scopes=["experiment:write"])
def duplicate(self, request: Request, *args: Any, **kwargs: Any) -> Response:
source_experiment: Experiment = self.get_object()
if experiment_has_legacy_metrics(source_experiment):
return Response(
{"detail": "Duplication is not supported for experiments using legacy metrics."},
status=400,
)
feature_flag_key = request.data.get("feature_flag_key")
name = request.data.get("name")
service = ExperimentService(team=self.team, user=request.user)
duplicate_experiment = service.duplicate_experiment(
source_experiment,
feature_flag_key=feature_flag_key,
name=name,
serializer_context=self.get_serializer_context(),
)
return Response(
ExperimentSerializer(duplicate_experiment, context=self.get_serializer_context()).data, status=201
)
@extend_schema(
request=None,
responses=ExperimentSerializer,
)
@action(methods=["POST"], detail=True, required_scopes=["experiment:write"])
def migrate(self, request: Request, *args: Any, **kwargs: Any) -> Response:
"""
Move a legacy experiment onto the new experiments engine.
Creates a new experiment with the same configuration and its metrics converted
to the new format, and returns it. Legacy experiments no longer show results,
so this is how to get results for one. The legacy experiment is left untouched,
so the project ends up with two experiments. Both point at the same feature
flag, so no new rollout is needed and users keep the variant they already have.
Legacy shared metrics used by the experiment are converted as part of the same
call. Each one gets a new shared metric, and the new experiment links to that.
Calling this again returns the experiment created the first time instead of
making another copy.
Returns 400 if the experiment already uses the new engine.
"""
refuse_scout_experiment_migrate(is_scout_sandbox_request(request))
experiment: Experiment = self.get_object()
if not experiment_has_legacy_metrics(experiment):
raise ValidationError(
"This experiment already uses the new experiments engine, so there is nothing to migrate."
)
try:
migration = migrate_legacy_experiment(experiment.id, self.team.id, migrate_shared_metrics=True)
except (LegacyMigrationError, ValueError) as e:
raise ValidationError(f"Couldn't migrate this experiment: {e}. Contact support if it keeps happening.")
return Response(ExperimentSerializer(migration.experiment, context=self.get_serializer_context()).data)
@extend_schema(
request=CreateFromPromptInputSerializer,
responses=ExperimentSerializer,
)
@action(
methods=["POST"],
detail=False,
url_path="create_from_prompt",
# Endpoint reads an LLMPrompt's name + versions to validate input, so the caller
# needs prompt-read scope in addition to experiment-write. Without llm_prompt:read,
# a token with experiment:write alone could enumerate existing prompts by guessing
# names.
required_scopes=["experiment:write", "llm_prompt:read"],
)
def create_from_prompt(self, request: Request, *args: Any, **kwargs: Any) -> Response:
"""
Create an experiment that compares N versions of an LLM prompt using a metric template.
The user picks 2+ versions of an existing LLMPrompt and 1+ metric templates
(cost / latency / eval_pass_rate). The endpoint builds the matching variants
(control + test-N, each named after its prompt version) and attaches one
metric per selected template, each scoped to the prompt's $ai_prompt_name.
Resulting experiment is in draft state.
"""
# Scope checks alone don't cover resource-level access controls: this action runs on the
# experiment viewset, so AccessControlPermission only verifies experiment access. Check
# prompt access explicitly before validation queries LLMPrompt and leaks which names exist.
if not self.user_access_control.check_access_level_for_resource("llm_prompt", required_level="viewer"):
raise PermissionDenied("Creating an experiment from a prompt requires LLM analytics access.")
serializer = CreateFromPromptInputSerializer(data=request.data, context={"team": self.team})
serializer.is_valid(raise_exception=True)
data = serializer.validated_data
prompt_name: str = data["prompt_name"]
versions: list[int] = data["versions"]
templates: list[str] = data["templates"]
versions_label = ", ".join(f"v{v}" for v in versions)
templates_label = ", ".join(templates)
name = data.get("name") or f"{prompt_name}: {versions_label} ({templates_label})"
feature_flag_key = data.get("feature_flag_key") or _slugify_feature_flag_key(name, team_id=self.team.id)
metrics: list[dict[str, Any]] = []
for template in templates:
metric_dict = build_template(template, prompt_name).model_dump(exclude_none=True)
metric_dict.setdefault("kind", "ExperimentMetric")
metrics.append(metric_dict)
variants = _build_prompt_variants(versions)
# Encode (prompt_name, prompt_version) as a JSON payload per variant so the SDK can
# read it via flags.get_flag_payload(...) instead of hard-coding a variant→version map.
feature_flag_payloads = {
variant["key"]: json.dumps({"prompt_name": prompt_name, "prompt_version": version})
for variant, version in zip(variants, versions)
}
service = ExperimentService(team=self.team, user=request.user)
experiment = service.create_experiment(
name=name,
feature_flag_key=feature_flag_key,
description=data.get("description", ""),
parameters={
"prompt_metadata": {
"name": prompt_name,
"templates": templates,
"versions": versions,
},
},
feature_flag_config={
"filters": {
"multivariate": {"variants": variants},
"groups": [{"properties": [], "rollout_percentage": 100}],
"payloads": feature_flag_payloads,
},
},
metrics=metrics,
serializer_context=self.get_serializer_context(),
allow_unknown_events=True,
)
return Response(
ExperimentSerializer(experiment, context=self.get_serializer_context()).data,
status=201,
)
@extend_schema(
request=None,
responses={
200: {
"type": "array",
"items": {
"type": "object",
"properties": {
"key": {"type": "string"},
"label": {"type": "string"},
"description": {"type": "string"},
},
"required": ["key", "label", "description"],
},
}
},
)
@action(
methods=["GET"],
detail=False,
url_path="prompt_templates",
required_scopes=["experiment:read"],
)
def prompt_templates(self, request: Request, *args: Any, **kwargs: Any) -> Response:
"""List the LLM metric templates that can be passed to `create_from_prompt`."""
return Response(list_templates())
@extend_schema(
request=CopyExperimentToProjectSerializer,
responses=ExperimentSerializer,
)
@action(methods=["POST"], detail=True, url_path="copy_to_project", required_scopes=["experiment:write"])
def copy_to_project(self, request: Request, *args: Any, **kwargs: Any) -> Response:
"""Copy an experiment into another project in the same organization as a new draft."""
refuse_scout_experiment_copy_to_project(is_scout_sandbox_request(request))
source_experiment: Experiment = self.get_object()
if experiment_has_legacy_metrics(source_experiment):
return Response(
{"detail": "Copying is not supported for experiments using legacy metrics."},
status=400,
)
request_serializer = CopyExperimentToProjectSerializer(data=request.data)
request_serializer.is_valid(raise_exception=True)
target_team_id = request_serializer.validated_data["target_team_id"]
target_team = Team.objects.filter(id=target_team_id, organization_id=self.team.organization_id).first()
if target_team is None:
return Response({"detail": "Target team not found."}, status=404)
self._check_copy_target_access(request, target_team)
feature_flag_key = request_serializer.validated_data.get("feature_flag_key")
name = request_serializer.validated_data.get("name")
service = ExperimentService(team=self.team, user=request.user)
new_experiment = service.copy_experiment_to_project(
source_experiment,
target_team,
feature_flag_key=feature_flag_key,
name=name,
serializer_context={
"request": request,
"team_id": target_team.id,
"project_id": target_team.project_id,
"get_team": lambda: target_team,
},
)
target_context = {
**self.get_serializer_context(),
"team_id": target_team.id,
"project_id": target_team.project_id,
"get_team": lambda: target_team,
}
return Response(ExperimentSerializer(new_experiment, context=target_context).data, status=201)
@action(methods=["POST"], detail=True, required_scopes=["experiment:write"])
def create_exposure_cohort_for_experiment(self, request: Request, *args: Any, **kwargs: Any) -> Response:
experiment = self.get_object()
service = ExperimentService(team=self.team, user=request.user)
cohort = service.create_exposure_cohort(
experiment,
serializer_context={
"request": request,
"team": self.team,
"team_id": self.team_id,
},
)
cohort_data = CohortSerializer(cohort, context={"request": request, "team": self.team}).data
return Response({"cohort": cohort_data}, status=201)
@extend_schema(
parameters=[
OpenApiParameter(
name="metric_uuid",
type=str,
location=OpenApiParameter.QUERY,
description=(
"UUID of the metric to fetch timeseries for. Available on each metric in the "
"experiment's metrics array."
),
required=True,
),
OpenApiParameter(
name="fingerprint",
type=str,
location=OpenApiParameter.QUERY,
description=(
"Ignored. The server derives the metric's calculation key from the experiment's current "
"settings. Accepted so that existing clients keep working."
),
required=False,
deprecated=True,
),
],
)
@action(methods=["GET"], detail=True, required_scopes=["experiment:read"])
def timeseries_results(self, request: Request, *args: Any, **kwargs: Any) -> Response:
experiment = self.get_object()
metric_uuid = request.query_params.get("metric_uuid")
if not metric_uuid:
raise ValidationError("metric_uuid query parameter is required")
service = ExperimentService(team=self.team, user=request.user)
return Response(service.get_timeseries_results(experiment, metric_uuid=metric_uuid))
@action(methods=["POST"], detail=True, required_scopes=["experiment:write"])
def recalculate_timeseries(self, request: Request, *args: Any, **kwargs: Any) -> Response:
experiment = self.get_object()
# Only the metric's uuid is read, and a `fingerprint` in the body is ignored: the service derives the
# definition and the key from the experiment.
metric = request.data.get("metric")
if not isinstance(metric, dict) or not metric:
raise ValidationError("metric is required")
service = ExperimentService(team=self.team, user=request.user)
result = service.request_timeseries_recalculation(experiment, metric_uuid=metric.get("uuid") or "")
is_existing = result.pop("is_existing", False)
if not is_existing:
recalculation_id = str(result["id"])
try:
temporal = sync_connect()
asyncio.run(
temporal.start_workflow(
"experiment-timeseries-recalculation-workflow",
ExperimentTimeseriesRecalculationWorkflowInputs(recalculation_id=recalculation_id),
id=f"experiment-recalculation-{recalculation_id}",
task_queue=settings.GENERAL_PURPOSE_TASK_QUEUE,
)
)
except Exception:
# team-scoped filter: defense in depth so the rollback can never reach across teams even if
# recalculation_id were ever sourced from somewhere less trusted than the row we just created.
ExperimentTimeseriesRecalculation.objects.filter(team=self.team, id=recalculation_id).update(
status=ExperimentTimeseriesRecalculation.Status.FAILED
)
raise
status_code = 200 if is_existing else 201
return Response(result, status=status_code)
@extend_schema(
request=RecalculateMetricsRequestSerializer,
responses={
200: ExperimentMetricsRecalculationJobSerializer,
201: ExperimentMetricsRecalculationJobSerializer,
429: OpenApiResponse(
description=(
"A manual trigger arrived less than five minutes after the latest completed run finished. "
"Retry-After carries the seconds until the next run is allowed."
)
),
},
)
@action(
methods=["POST"],
detail=True,
url_path="metrics_recalculation",
required_scopes=["experiment:write"],
)
def metrics_recalculation(self, request: Request, *args: Any, **kwargs: Any) -> Response:
"""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. An experiment that started too long ago gets 201 with
a run that is already failed: every metric carries the `recalculation_window_too_long` error in
`metric_errors`, no workflow starts, and a retry gets the same answer. 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.
"""
experiment: Experiment = self.get_object()
request_serializer = RecalculateMetricsRequestSerializer(data=request.data)
request_serializer.is_valid(raise_exception=True)
is_mcp_client = request.headers.get("x-posthog-client") == "mcp"
trigger = (
ExperimentMetricsRecalculation.Trigger.AGENT_MCP
if is_mcp_client
else request_serializer.validated_data["trigger"]
)
# request.user is User | AnonymousUser at the DRF level; the viewset enforces auth so it's a User here.
result = request_recalculation(experiment, cast(User, request.user), trigger)
# Read without mutating — the serializer surfaces is_existing on the response so clients can detect
# the idempotent-reuse path without inspecting the HTTP status code.
is_existing = result.get("is_existing", False)
# A rejected run is new but already FAILED, so it gets a 201 and no workflow.
if not is_existing and result["status"] == ExperimentMetricsRecalculation.Status.PENDING:
start_metrics_recalculation_workflow(
str(result["id"]),
team_id=experiment.team_id,
organization_id=str(experiment.team.organization_id),
)
return Response(
ExperimentMetricsRecalculationJobSerializer(result).data,
status=200 if is_existing else 201,
)
@extend_schema(responses={200: ExperimentMetricsRecalculationLatestSerializer, 404: None})
@action(
methods=["GET"],
detail=True,
# NOTE: this action is declared BEFORE the by-id action so its URL pattern wins on /latest/.
url_path="metrics_recalculation/latest",
required_scopes=["experiment:read"],
)
def metrics_recalculation_latest(self, request: Request, *args: Any, **kwargs: Any) -> Response:
experiment: Experiment = self.get_object()
active = get_active_recalculation(experiment)
active_run = {"id": str(active.id), "status": active.status} if active is not None else None
recalc = get_latest_recalculation(experiment)
if recalc is not None:
return Response(_serialize_latest(_build_run_payload(recalc), active_run))
# Cold start: no terminal run worth showing. Fall back to the latest timeseries data as a read-only
# placeholder so the user sees results immediately, even while a first run is active (its pending
# payload would blank them out); an active run still rides along for polling. Pure read, no
# workflow start.
fallback = build_timeseries_cold_start_payload(experiment)
if fallback is not None:
return Response(_serialize_latest(fallback, active_run))
if active is not None:
return Response(_serialize_latest(_build_run_payload(active), active_run))
return Response({"detail": "No completed recalculation found"}, status=404)
@extend_schema(
parameters=[
OpenApiParameter(
name="recalculation_id",
location=OpenApiParameter.PATH,
# Keep the URL's UUID pattern in the schema; declaring a bare UUID type drops it.
type={
"type": "string",
"pattern": r"^[0-9a-fA-F]{8}-[0-9a-fA-F]{4}-[0-9a-fA-F]{4}-[0-9a-fA-F]{4}-[0-9a-fA-F]{12}$",
},
description=(
"UUID of the recalculation run to fetch. This is the run's own id, not the experiment id."
),
)
],
responses={200: ExperimentMetricsRecalculationRunSerializer, 404: None},
)
@action(
methods=["GET"],
detail=True,
# Strict UUID regex so 'latest' (the sibling action above) never matches this route.
url_path=r"metrics_recalculation/(?P<recalculation_id>[0-9a-fA-F]{8}-[0-9a-fA-F]{4}-[0-9a-fA-F]{4}-[0-9a-fA-F]{4}-[0-9a-fA-F]{12})",
required_scopes=["experiment:read"],
)
def metrics_recalculation_detail(
self, request: Request, recalculation_id: str, *args: Any, **kwargs: Any
) -> Response:
experiment: Experiment = self.get_object()
recalc = get_recalculation_by_id(experiment, recalculation_id)
if recalc is None:
return Response({"detail": "Recalculation not found"}, status=404)
return Response(ExperimentMetricsRecalculationRunSerializer(_build_run_payload(recalc)).data)
@action(methods=["GET"], detail=False, url_path="stats", required_scopes=["experiment:read"])
def stats(self, request: Request, **kwargs: Any) -> Response:
service = ExperimentService(team=self.team, user=request.user)
return Response(service.get_velocity_stats())
@validated_request(
query_serializer=RunningTimeTargetQuerySerializer,
responses={200: OpenApiResponse(response=RunningTimeTargetSerializer)},
)
@action(methods=["GET"], detail=True, url_path="running_time_target", required_scopes=["experiment:read"])
def running_time_target(self, request: ValidatedRequest, *args: Any, **kwargs: Any) -> Response:
"""The target sample of the experiment's running time estimate, which the experiment page's header compares
with the exposures so far, and what the experiment can detect over time.
In manual running time mode it is the saved target. Otherwise it is sized from the first primary metric's
current result: the variance the analysis uses (with CUPED when the analysis applied it) and the flag's
traffic split, so that the comparison of each variant with the control reaches the minimum detectable effect.
"""
experiment: Experiment = self.get_object()
target = get_running_time_target(
team_id=self.team.id,
experiment_id=experiment.id,
mode=RunningTimeMode(mode) if (mode := request.validated_query_data.get("mode")) else None,
)
return Response(RunningTimeTargetSerializer(target).data)
@validated_request(
request_serializer=RunningTimeCalculationInputSerializer,
responses={200: OpenApiResponse(response=RunningTimeCalculationResultSerializer)},
)
@action(
methods=["POST"],
detail=False,
url_path="calculate_running_time",
required_scopes=["experiment:read"],
)
def calculate_running_time(self, request: ValidatedRequest, **kwargs: Any) -> Response:
"""Estimate the recommended sample size and running time for an experiment.
Pure statistical calculation — does not read or write any experiment. Pass the metric type, a
minimum detectable effect, and either a baseline value or raw baseline statistics. When
`exposure_rate_per_day` is provided, the response also includes the estimated running time in days.
"""
data = request.validated_data
metric_type = data["metric_type"]
mde = data["minimum_detectable_effect"]
number_of_variants = data["number_of_variants"]
exposure_rate = data.get("exposure_rate_per_day")
baseline: BaselineStats | None = None
stats = data.get("baseline_stats")
if stats is not None:
baseline = BaselineStats(
number_of_samples=stats["number_of_samples"],
sum=stats["sum"],
sum_squares=stats.get("sum_squares", 0.0),
denominator_sum=stats.get("denominator_sum"),
denominator_sum_squares=stats.get("denominator_sum_squares"),
numerator_denominator_sum_product=stats.get("numerator_denominator_sum_product"),
step_counts=stats.get("step_counts") or [],
)
baseline_value = data.get("baseline_value")
if baseline_value is None and baseline is not None:
baseline_value = calculate_baseline_value(baseline, metric_type)
variance = data.get("variance")
if variance is None and baseline_value is not None:
if baseline is not None:
variance = calculate_variance_from_stats(baseline_value, metric_type, baseline)
else:
variance = calculate_variance(metric_type, baseline_value)
recommended_sample_size: int | None = None
if baseline_value is not None:
recommended_sample_size = calculate_sample_size(
metric_type, baseline_value, mde, number_of_variants, variance
)
return Response(
{
"baseline_value": baseline_value,
"variance": variance,
"recommended_sample_size": recommended_sample_size,
"recommended_running_time_days": calculate_running_time_days(recommended_sample_size, exposure_rate),
}
)
@validated_request(
request_serializer=ExperimentSetupContextInputSerializer,
responses={200: OpenApiResponse(response=ExperimentSetupContextResponseSerializer)},
)
@action(
methods=["POST"],
detail=False,
url_path="setup_context",
# The response carries saved-metric definitions and reuse counts, which the saved-metric
# API gates behind its own scope. Object-level filtering does not check token scopes.
# It also counts arbitrary events across the project, which /query/ gates behind query:read.
required_scopes=["experiment:read", "experiment_saved_metric:read", "query:read"],
throttle_classes=[ClickHouseBurstRateThrottle, ClickHouseSustainedRateThrottle],
)
def setup_context(self, request: ValidatedRequest, **kwargs: Any) -> Response:
"""Facts about this project that decide how to configure a new experiment.
Returns the team's experiment defaults, which SDKs call feature flags, traffic on a target
surface, the baseline of a candidate metric, how recent experiments were set up, and the
most reused shared metrics. Each section has its own status, so a slow or failed read
leaves the others valid. POST because the inputs describe a plan rather than a resource;
the endpoint only reads.
"""
if not self._setup_context_enabled():
raise NotFound()
data = request.validated_data
# detail=False actions skip the automatic list-action ACL filtering, so filter here: the
# response names experiments and shared metrics, which must respect object-level access.
experiments = self.user_access_control.filter_queryset_by_access_level(
Experiment.objects.filter(team_id=self.team.pk)
)
saved_metrics = self.user_access_control.filter_queryset_by_access_level(
ExperimentSavedMetric.objects.filter(team_id=self.team.pk), resource="experiment_saved_metric"
)
context = build_setup_context(
team=self.team,
inputs=SetupContextInputs(
target_event=data.get("target_event") or None,
target_url_contains=data.get("target_url_contains") or None,
target_properties=tuple(data.get("target_properties") or ()),
metric_event=data.get("metric_event") or None,
metric_properties=tuple(data.get("metric_properties") or ()),
previous_experiments_limit=data["previous_experiments_limit"],
shared_metrics_limit=data["shared_metrics_limit"],
),
experiments=experiments,
saved_metrics=saved_metrics,
)
return Response(ExperimentSetupContextResponseSerializer(context).data)
def _setup_context_enabled(self) -> bool:
# In a loginas impersonation session request.user is the customer. The flag is evaluated for the staff
# user, so support can read a customer's setup context without the flag being on for that customer.
# OAuth impersonation (MCP) has no session, so it keeps the customer's flag, which also gates the tool.
flag_user = get_original_user_from_session(self.request) if is_impersonated_session(self.request) else None
try:
return posthog_feature_flag_enabled(
EXPERIMENT_SETUP_CONTEXT_FLAG,
str((flag_user or cast(User, self.request.user)).distinct_id),
organization_id=self.organization_id,
team_id=self.team.id,
)
except Exception:
logger.warning("Failed to evaluate the experiment setup context flag", exc_info=True)
return False
@extend_schema(
description=(
"Resolve which experiments (and variants) a session recording saw. Variants come from the session's "
"$feature_flag_called events and stamped $feature/<key> event properties — flag evaluation, which may "
"differ from an experiment's exposure criteria."
),
parameters=[
OpenApiParameter(
name="session_id",
location=OpenApiParameter.QUERY,
type=str,
required=True,
description="ID of the session recording to resolve experiment context for.",
),
],
responses={200: OpenApiResponse(response=ExperimentSessionContextResponseSerializer)},
)
@action(
methods=["GET"],
detail=False,
url_path="session_context",
required_scopes=["experiment:read", "session_recording:read"],
throttle_classes=[ClickHouseBurstRateThrottle, ClickHouseSustainedRateThrottle],
)
def session_context(self, request: Request, **kwargs: Any) -> Response:
session_id = (request.query_params.get("session_id") or "").strip()
if not session_id:
raise ValidationError({"session_id": ["This field is required."]})
if not self.user_access_control.check_access_level_for_resource("session_recording", required_level="viewer"):
raise PermissionDenied("Reading session experiment context requires session replay access.")
if not _accessible_session_ids(request, self.user_access_control, self.team, [session_id]):
raise PermissionDenied("You don't have access to this recording.")
# detail=False actions skip the automatic list-action ACL filtering, so filter here —
# private experiments must not leak into another user's session context.
experiments = self.user_access_control.filter_queryset_by_access_level(
Experiment.objects.filter(team_id=self.team.pk)
)
# user threads through to the HogQL queries: exposure criteria can filter on arbitrary
# properties, which must respect the viewer's property-level access control.
items = get_session_experiment_context(
team=self.team, session_id=session_id, experiments=experiments, user=cast(User, request.user)
)
if items is None:
raise NotFound("Recording not found")
serializer = ExperimentSessionContextResponseSerializer({"session_id": session_id, "results": items})
return Response(serializer.data)
@validated_request(
request_serializer=ExperimentSessionContextsRequestSerializer,
responses={200: OpenApiResponse(response=ExperimentSessionContextsResponseSerializer)},
)
@action(
methods=["POST"],
detail=False,
url_path="session_contexts",
required_scopes=["experiment:read", "session_recording:read"],
# Not the ClickHouse* pair the single-session action uses: that pair only limits
# personal-API-key traffic, and this endpoint's primary caller is the
# session-authenticated web app.
throttle_classes=[SessionContextsBurstRateThrottle, SessionContextsSustainedRateThrottle],
)
def session_contexts(self, request: ValidatedRequest, **kwargs: Any) -> Response:
"""Resolve experiment context for a batch of session recordings.
Batch variant of `session_context`, used to prefetch the replay player's experiments
box for a whole recordings list in one request. POST because the id list doesn't fit a
query string; the endpoint only reads. Already-computed sessions are served from (and
cold ones written to) the same short-lived per-viewer cache the single-session endpoint
uses, so opening any prefetched recording renders its context instantly. Sessions whose
recording metadata doesn't exist yet are omitted from the response, as are recordings
the caller can't access and sessions beyond the batch's recording-day budget (each
distinct recording day costs its own set of ClickHouse scans, so only the most recent
days are computed per request).
"""
session_ids: list[str] = request.validated_data["session_ids"]
if not self.user_access_control.check_access_level_for_resource("session_recording", required_level="viewer"):
raise PermissionDenied("Reading session experiment context requires session replay access.")
# Denied recordings are omitted rather than rejecting the batch, matching how the response
# already treats a session whose recording metadata doesn't exist.
session_ids = _accessible_session_ids(request, self.user_access_control, self.team, session_ids)
# detail=False actions skip the automatic list-action ACL filtering, so filter here —
# private experiments must not leak into another user's session context.
experiments = self.user_access_control.filter_queryset_by_access_level(
Experiment.objects.filter(team_id=self.team.pk)
)
contexts = get_session_experiment_contexts(
team=self.team, session_ids=session_ids, experiments=experiments, user=cast(User, request.user)
)
serializer = ExperimentSessionContextsResponseSerializer(
{"results": [{"session_id": session_id, "results": items} for session_id, items in contexts.items()]}
)
return Response(serializer.data)
@extend_schema(
request=None,
responses={200: OpenApiResponse(response=ExperimentInSessionExposureSerializer)},
)
@action(methods=["GET"], detail=True, url_path="in_session_exposure", required_scopes=["experiment:read"])
def in_session_exposure(self, request: Request, *args: Any, **kwargs: Any) -> Response:
"""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.
"""
experiment: Experiment = self.get_object()
semantics = resolve_in_session_exposure_semantics(team_id=self.team_id, experiment_id=experiment.id)
if semantics is None:
raise NotFound()
return Response(ExperimentInSessionExposureSerializer(semantics).data)
@validated_request(
request_serializer=ExperimentSessionBucketRequestSerializer,
responses={200: OpenApiResponse(response=ExperimentSessionBucketResponseSerializer)},
)
@action(
methods=["POST"],
detail=True,
url_path="session_buckets",
required_scopes=["experiment:read", "session_recording:read"],
# Heavier than the session-context batch (it scans the run window rather than a known id
# list) and called by the session-authenticated web app, which the ClickHouse* pair
# doesn't cover.
throttle_classes=[SessionBucketsBurstRateThrottle, SessionBucketsSustainedRateThrottle],
)
def session_buckets(self, request: ValidatedRequest, **kwargs: Any) -> Response:
"""Session recordings of this experiment matching a bucket.
Answers the questions a recordings query can't express on its own — "fired any of these
metrics", "fired none of them", "was exposed but never completed the funnel in this
session" — by returning a bounded, most-recent-first list of session IDs to pass back as
a recordings query's session_ids. POST because the metric list doesn't fit a query
string; the endpoint only reads.
Session-scoped and goal-free: the set describes what happened in each session, while the
experiment analysis counts per person over the whole run window. A session can be in the
drop-off bucket while the same person converts in a later one.
"""
experiment: Experiment = self.get_object()
if not self.user_access_control.check_access_level_for_resource("session_recording", required_level="viewer"):
raise PermissionDenied("Reading experiment session buckets requires session replay access.")
try:
scan = get_experiment_session_bucket(
team=self.team,
# user threads through to the HogQL query: metric sources and exposure criteria
# can filter on arbitrary properties, which must respect the viewer's
# property-level access control.
user=cast(User, request.user),
experiment=experiment,
bucket=ExperimentSessionBucket(request.validated_data["bucket"]),
metric_uuids=request.validated_data["metric_uuids"],
variant=request.validated_data["variant"],
limit=request.validated_data["limit"],
)
except SessionBucketUnavailable as error:
raise ValidationError(str(error))
# Applied to the computed set rather than inside the scan: the bucket is cached per
# viewer, so filtering on read honors a revocation that lands while an entry is warm. The
# cut to `limit` follows it, so a denied recording never spends a returned slot and
# `truncated` describes what this viewer may see.
result = finalize_session_bucket(
scan,
_accessible_session_ids(request, self.user_access_control, self.team, scan.candidate_session_ids),
)
return Response(ExperimentSessionBucketResponseSerializer(result).data)
@validated_request(
request_serializer=ExperimentSessionEventDeltaRequestSerializer,
responses={200: OpenApiResponse(response=ExperimentSessionEventDeltaResponseSerializer)},
)
@action(
methods=["POST"],
detail=True,
url_path="session_event_deltas",
required_scopes=["experiment:read", "session_recording:read"],
# The heaviest read in this family: it compares every event name in the window, so unlike
# the bucket scan there is no event-name predicate for ClickHouse to prune on.
throttle_classes=[SessionEventDeltasBurstRateThrottle, SessionEventDeltasSustainedRateThrottle],
)
def session_event_deltas(self, request: ValidatedRequest, **kwargs: Any) -> Response:
"""The recordings worth watching for this experiment, grouped into cards.
Each card is one sentence and the recordings that back it: an event one variant did clearly
more than the others, an error signal concentrated in one variant, or a shortcut to a
metric event happening on screen. Every card's count is a count of recordings that actually
exist, so handing its session ids to the recordings list can't come back empty. POST to
take the same throttle and cache posture as the other reads in this family rather than
because it carries a body: it takes no parameters, and it only reads.
It reports no effect size. Cards carry a direction and a band rather than a rate, a ratio
or a person count: the experiment's results already state magnitudes, computed per person
over the whole run window, and this reads one session per person over a clamped one. Two
numbers for the same event would read as a contradiction, so this surface states none. That
is what lets a card sit on one of the experiment's own metric events, which it names, so a
reader is sent to the results rather than given a second answer.
"""
experiment: Experiment = self.get_object()
if not self._session_event_deltas_enabled():
raise NotFound()
if not self.user_access_control.check_access_level_for_resource("session_recording", required_level="viewer"):
raise PermissionDenied("Comparing an experiment's session behavior requires session replay access.")
try:
result = get_experiment_session_event_deltas(
team=self.team,
# user threads through to the HogQL queries: exposure criteria can filter on
# arbitrary properties, which must respect the viewer's property-level access
# control.
user=cast(User, request.user),
experiment=experiment,
)
except SessionEventDeltasUnavailable as error:
raise ValidationError(str(error))
# Applied to the computed shelf rather than inside the scan, as the session buckets do it:
# the shelf is cached across viewers sharing a restriction profile, so filtering on read is
# what keeps one viewer's entry from leaking another's denied recordings, and a revocation
# lands even while an entry is warm. The resource-level check above grants the replay
# product, not every recording in it — without this a viewer denied one recording could
# still read its id, the variant it was in, and an event it contains.
result = finalize_watch_cards(
result,
_accessible_session_ids(request, self.user_access_control, self.team, all_card_session_ids(result)),
)
return Response(ExperimentSessionEventDeltaResponseSerializer(result).data)
def _session_event_deltas_enabled(self) -> bool:
# Scoped to the experiment's organization rather than the caller's current one: a user in
# several orgs could otherwise switch their current org to a flagged-in one and read an
# experiment in an org that is not.
try:
return posthog_feature_flag_enabled(
EXPERIMENT_BEHAVIOR_COMPARISON_FLAG,
str(cast(User, self.request.user).distinct_id),
organization_id=self.organization_id,
team_id=self.team.id,
)
except Exception:
logger.warning("Failed to evaluate the experiment behavior comparison flag", exc_info=True)
return False
def _build_run_payload(recalc: ExperimentMetricsRecalculation) -> dict:
results = get_run_results(recalc)
payload = build_job_payload(recalc, results=results, include_live_progress=True)
payload["results"] = results
return payload
def _serialize_latest(payload: dict, active_run: dict | None) -> dict:
if active_run is not None:
payload["active_run"] = active_run
return ExperimentMetricsRecalculationLatestSerializer(payload).data