/configuring-experiment-analytics

name: configuring-experiment-analytics
description: Configures the analytics side of a PostHog experiment — exposure criteria (server-resolved default exposure event vs custom exposure events), primary and secondary metrics, the supported metric types (count, sum, ratio with `math` and `math_property`, retention with `retention_window_start` and `start_handling`, percentile with `quantile`), multivariate user handling ("Exclude from analysis" vs "Use first seen variant"), and how to read results once the experiment is live. Use when the user adds or edits a primary or secondary metric (e.g. "add a secondary metric tracking 'downloaded_file' per user"), sets up a ratio metric (e.g. "revenue from purchase_completed / pageviews"), sets up a retention metric (e.g. "$pageview → uploaded_file, 7-day window"), configures custom exposure (e.g. "only count users who hit /checkout"), changes multivariate handling, or asks "who is in the analysis?", "how do I measure impact?", "is this winning?", "what's the confidence level?", or "should I ship?".

Configuring experiment analytics

This skill answers: **Who is included in the analysis?** and **How to measure impact?**

Exposure criteria

Exposure criteria determine which users are counted in the experiment analysis.

Exposure event

Two options:

1. **Default exposure event** — users are included when the experiment's default exposure event fires for the experiment's flag: `$feature_flag_called`, or `$experiment_exposure` for newer experiments. Which one applies is resolved server-side — read `resolved_exposure_event` from `experiment-get` rather than assuming either name (both events carry the same properties). When it is `$feature_flag_called`, also read `$experiment_exposure` (`event IN ('$feature_flag_called', '$experiment_exposure')`), and count persons, not rows. This is the standard approach — it means a user is included only when they actually encounter the feature flag in your code. 2. **Custom exposure event** — users are included when a specific custom event fires. Use this when you want tighter control over who enters the analysis (e.g., only users who actually visit the page where the experiment runs).

Filters on the exposure event remove individual events, not users. A user still counts as long as one of their exposure events passes the filters. To keep users out of the experiment, exclude them in the flag's release conditions before launch (see `configuring-experiment-rollout`).

Multiple variant handling

When a user is exposed to multiple variants (e.g., due to flag changes or race conditions):

• **Exclude from analysis** — removes these users from the analysis entirely. Cleaner data, smaller sample.
• **Use first seen variant** — assigns users to the first variant they were exposed to. Keeps all users in the analysis. Note that "first seen" can introduce other biases as

behavior cannot be clearly attributed to a single variant and is not recommended unless necessary.

**Bias risk on uneven splits.** "Exclude from analysis" combined with an uneven variant split can introduce bias — multi-variant users are dropped asymmetrically and the smaller variant loses a larger fraction of its assignments. If those users behave differently from the rest, the smaller variant's metrics will be skewed.

The right mitigation depends on experiment state:

• **Not yet launched, or only exposed to a few users so far** — switch to an even variant split and

use the overall rollout percentage to limit test-variant exposure. This removes the bias and preserves statistical power. See `configuring-experiment-rollout`.

• **Live experiment with significant exposures** — changing the split mid-run reassigns users across

variants, which is bad for user experience and data quality. Switch this setting to "Use first seen variant" instead — it keeps already-assigned users in their original variant (no reassignment) and removes the asymmetric exclusion.

Filter test accounts

`exposure_criteria.filterTestAccounts` (default: true) — excludes internal/test users from the analysis.

Resolving experiments

Metric changes require an experiment ID. If the user refers to an experiment by name or description (e.g. "add metrics to the checkout test"), load the `finding-experiments` skill to resolve it to a concrete ID before proceeding.

Metrics

A metric reaches an experiment one of two ways, both via `experiment-update`:

• **Inline metric** — defined directly on the experiment. Sent in the `metrics` array, which

**replaces** the entire inline list, so always get the current experiment first via `experiment-get` to preserve existing metrics.

• **Shared (saved) metric** — a reusable metric object that can be attached to many experiments.

Attached by ID via `saved_metrics_ids` (this list also **replaces** the experiment's existing saved-metric links, so resend the full set — see Step 1).

**Prefer reusing a shared metric over duplicating it inline.** Build a new inline metric only when no suitable shared metric already exists.

Step 1: Check for an existing shared metric (REQUIRED — match by definition, not name)

Before building any new inline metric, you MUST check whether the project already has a shared (saved) metric that measures the same thing, and reuse it. Duplicating a metric that already exists as a shared metric fragments measurement and is exactly what we want to avoid.

**Reuse is decided by the metric _definition_ — the event or action plus the metric type — not the name.** Saved metrics are named by each team's own conventions, which you cannot guess, so you must compare on what each metric measures (its `query`), never on its title.

**Workflow:**

1. **Know what you're about to build first.** Settle the target event(s)/action(s) and metric type (mean / funnel / ratio / retention / quantile) before searching — see Step 2 to confirm the event exists via `read-data-schema`. You can only recogniz