Skip to content

: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.

110 KB
Raw Blame
"""
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