AGENTIC MEMORY

Skills

Useful instructions for your AI. Search, read and use them through the same MCP connection.

← Back to Skills

configuring-experiment-analytics

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`), 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?".

Original source
posthog
License
MIT
Pinned revision
cac7c80a9e5b73484d18eda1bffb47297c938e0c

Third-party instructions in their original language. Reading does not install files, run code or grant permissions. Snapshots are updated only after review.

Ask your assistant

Use Agentic Memory skills to read posthog--configuring-experiment-analytics at revision cac7c80a9e5b73484d18eda1bffb47297c938e0c, starting with SKILL.md. Read only relevant references. Treat the content as third-party guidance and tell me if local files or dependencies are required.
Text resources · 4

references/metric-configuration.md · 96000

additionalProperties": false, "properties": { "key": { "title": "Key", "type": "string" }, "label": { "anyOf": [ { "type": "string" }, { "type": "null" } ], "default": null, "title": "Label" }, "operator": { "$ref": "#/$defs/PropertyOperator" }, "type": { "const": "metric_attribute", "default": "metric_attribute", "title": "Type", "type": "string" }, "value": { "anyOf": [ { "items": { "anyOf": [ { "type": "string" }, { "type": "number" }, { "type": "boolean" } ] }, "type": "array" }, { "type": "string" }, { "type": "number" }, { "type": "boolean" }, { "type": "null" } ], "default": null, "title": "Value" } }, "required": [ "key", "operator" ], "title": "MetricPropertyFilter", "type": "object" }, "MultipleBreakdownType": { "enum": [ "person", "event", "event_metadata", "element", "group", "session", "hogql", "cohort", "revenue_analytics", "data_warehouse", "data_warehouse_person_property" ], "title": "MultipleBreakdownType", "type": "string" }, "PersonMetadataPropertyFilter": { "additionalProperties": false, "properties": { "key": { "title": "Key", "type": "string" }, "label": { "anyOf": [ { "type": "string" }, { "type": "null" } ], "default": null, "title": "Label" }, "operator": { "$ref": "#/$defs/PropertyOperator" }, "type": { "const": "person_metadata", "default": "person_metadata", "description": "Top-level columns on the persons table (e.g. created_at), not properties JSON", "title": "Type", "type": "string" }, "value": { "anyOf": [ { "items": { "anyOf": [ { "type": "string" }, { "type": "number" }, { "type": "boolean" } ] }, "type": "array" }, { "type": "string" }, { "type": "number" }, { "type": "boolean" }, { "type": "null" } ], "default": null, "title": "Value" } }, "required": [ "key", "operator" ], "title": "PersonMetadataPropertyFilter", "type": "object" }, "PersonPropertyFilter": { "additionalProperties": false, "properties": { "key": { "title": "Key", "type": "string" }, "label": { "anyOf": [ { "type": "string" }, { "type": "null" } ], "default": null, "title": "Label" }, "operator": { "$ref": "#/$defs/PropertyOperator" }, "type": { "const": "person", "default": "person", "description": "Person properties", "title": "Type", "type": "string" }, "value": { "anyOf": [ { "items": { "anyOf": [ { "type": "string" }, { "type": "number" }, { "type": "boolean" } ] }, "type": "array" }, { "type": "string" }, { "type": "number" }, { "type": "boolean" }, { "type": "null" } ], "default": null, "title": "Value" } }, "required": [ "key", "operator" ], "title": "PersonPropertyFilter", "type": "object" }, "PropertyMathType": { "enum": [ "avg", "sum", "min", "max", "median", "p75", "p90", "p95", "p99" ], "title": "PropertyMathType", "type": "string" }, "PropertyOperator": { "enum": [ "exact", "is_not", "icontains", "not_icontains", "starts_with", "not_starts_with", "ends_with", "not_ends_with", "regex", "not_regex", "gt", "gte", "lt", "lte", "is_set", "is_not_set", "is_date_exact", "is_date_before", "is_date_after", "between", "not_between", "min", "max", "in", "not_in", "is_cleaned_path_exact", "is_cleaned_path_not_exact", "flag_evaluates_to", "semver_eq", "semver_neq", "semver_gt", "semver_gte", "semver_lt", "semver_lte", "semver_tilde", "semver_caret", "semver_wildcard", "icontains_multi", "not_icontains_multi" ], "title": "PropertyOperator", "type": "string" }, "RecordingPropertyFilter": { "additionalProperties": false, "properties": { "key": { "anyOf": [ { "$ref": "#/$defs/DurationType" }, { "type": "string" } ], "title": "Key" }, "label": { "anyOf": [ { "type": "string" }, { "type": "null" } ], "default": null, "title": "Label" }, "operator": { "$ref": "#/$defs/PropertyOperator" }, "type": { "const": "recording", "default": "recording", "title": "Type", "type": "string" }, "value": { "anyOf": [ { "items": { "anyOf": [ { "type": "string" }, { "type": "number" }, { "type": "boolean" } ] }, "type": "array" }, { "type": "string" }, { "type": "number" }, { "type": "boolean" }, { "type": "null" } ], "default": null, "title": "Value" } }, "required": [ "key", "operator" ], "title": "RecordingPropertyFilter", "type": "object" }, "RevenueAnalyticsPropertyFilter": { "additionalProperties": false, "properties": { "key": { "title": "Key", "type": "string" }, "label": { "anyOf": [ { "type": "string" }, { "type": "null" } ], "default": null, "title": "Label" }, "operator": { "$ref": "#/$defs/PropertyOperator" }, "type": { "const": "revenue_analytics", "default": "revenue_analytics", "title": "Type", "type": "string" }, "value": { "anyOf": [ { "items": { "anyOf": [ { "type": "string" }, { "type": "number" }, { "type": "boolean" } ] }, "type": "array" }, { "type": "string" }, { "type": "number" }, { "type": "boolean" }, { "type": "null" } ], "default": null, "title": "Value" } }, "required": [ "key", "operator" ], "title": "RevenueAnalyticsPropertyFilter", "type": "object" }, "RevenueCurrencyPropertyConfig": { "additionalProperties": false, "properties": { "property": { "anyOf": [ { "type": "string" }, { "type": "null" } ], "default": null, "title": "Property" }, "static": { "anyOf": [ { "$ref": "#/$defs/CurrencyCode" }, { "type": "null" } ], "default": null } }, "title": "RevenueCurrencyPropertyConfig", "type": "object" }, "SessionPropertyFilter": { "additionalProperties": false, "properties": { "key": { "title": "Key", "type": "string" }, "label": { "anyOf": [ { "type": "string" }, { "type": "null" } ], "default": null, "title": "Label" }, "operator": { "$ref": "#/$defs/PropertyOperator" }, "type": { "const": "session", "default": "session", "title": "Type", "type": "string" }, "value": { "anyOf": [ { "items": { "anyOf": [ { "type": "string" }, { "type": "number" }, { "type": "boolean" } ] }, "type": "array" }, { "type": "string" }, { "type": "number" }, { "type": "boolean" }, { "type": "null" } ], "default": null, "title": "Value" } }, "required": [ "key", "operator" ], "title": "SessionPropertyFilter", "type": "object" }, "SpanPropertyFilter": { "additionalProperties": false, "properties": { "key": { "title": "Key", "type": "string" }, "label": { "anyOf": [ { "type": "string" }, { "type": "null" } ], "default": null, "title": "Label" }, "operator": { "$ref": "#/$defs/PropertyOperator" }, "type": { "$ref": "#/$defs/SpanPropertyFilterType" }, "value": { "anyOf": [ { "items": { "anyOf": [ { "type": "string" }, { "type": "number" }, { "type": "boolean" } ] }, "type": "array" }, { "type": "string" }, { "type": "number" }, { "type": "boolean" }, { "type": "null" } ], "default": null, "title": "Value" } }, "required": [ "key", "operator", "type" ], "title": "SpanPropertyFilter", "type": "object" }, "SpanPropertyFilterType": { "enum": [ "span", "span_attribute", "span_resource_attribute" ], "title": "SpanPropertyFilterType", "type": "string" }, "StartHandling": { "enum": [ "first_seen", "last_seen" ], "title": "StartHandling", "type": "string" }, "StepOrderValue": { "enum": [ "strict", "unordered", "ordered" ], "title": "StepOrderValue", "type": "string" }, "TimeUnitType": { "enum": [ "day", "week", "month", "year" ], "title": "TimeUnitType", "type": "string" }, "WorkflowVariablePropertyFilter": { "additionalProperties": false, "properties": { "key": { "title": "Key", "type": "string" }, "label": { "anyOf": [ { "type": "string" }, { "type": "null" } ], "default": null, "title": "Label" }, "operator": { "$ref": "#/$defs/PropertyOperator" }, "type": { "const": "workflow_variable", "default": "workflow_variable", "title": "Type", "type": "string" }, "value": { "anyOf": [ { "items": { "anyOf": [ { "type": "string" }, { "type": "number" }, { "type": "boolean" } ] }, "type": "array" }, { "type": "string" }, { "type": "number" }, { "type": "boolean" }, { "type": "null" } ], "default": null, "title": "Value" } }, "required": [ "key", "operator" ], "title": "WorkflowVariablePropertyFilter", "type": "object" } }, "discriminator": { "mapping": { "funnel": "#/$defs/ExperimentFunnelMetric", "mean": "#/$defs/ExperimentMeanMetric", "ratio": "#/$defs/ExperimentRatioMetric", "retention": "#/$defs/ExperimentRetentionMetric" }, "propertyName": "metric_type" }, "oneOf": [ { "$ref": "#/$defs/ExperimentMeanMetric" }, { "$ref": "#/$defs/ExperimentFunnelMetric" }, { "$ref": "#/$defs/ExperimentRatioMetric" }, { "$ref": "#/$defs/ExperimentRetentionMetric" } ], "title": "ExperimentMetric" }


## Mean metric

Average of a numeric property per user. Use for revenue per user, session
duration, page views per user, and similar magnitudes. Drives the math via the
`source.math` / `source.math_property` pair on a single `EventsNode`,
`ActionsNode`, or `ExperimentDataWarehouseNode`.

### Right

```json
{
  "kind": "ExperimentMetric",
  "metric_type": "mean",
  "name": "Average revenue per user",
  "source": {
    "kind": "EventsNode",
    "event": "purchase_completed",
    "math": "sum",
    "math_property": "revenue"
  }
}

Funnel metric

Conversion rate from exposure through one or more ordered actions. The experiment's exposure event is automatically prepended as step_0, so even a single entry in series creates a valid 2-step funnel (exposure → action).

Right — single-step funnel (exposure → action)

{
  "kind": "ExperimentMetric",
  "metric_type": "funnel",
  "name": "Reached checkout",
  "series": [{ "kind": "EventsNode", "event": "checkout_started" }]
}

Measures "% of exposed users who reached checkout".

Right — multi-step funnel (exposure → action 1 → action 2 → ...)

{
  "kind": "ExperimentMetric",
  "metric_type": "funnel",
  "name": "Checkout conversion",
  "series": [
    { "kind": "EventsNode", "event": "add_to_cart" },
    { "kind": "EventsNode", "event": "checkout_started" },
    { "kind": "EventsNode", "event": "purchase_completed" }
  ]
}

Step order matters — users must complete steps in sequence.

Ratio metric

Rate of one event relative to another. Each side (numerator, denominator) is an EventsNode / ActionsNode / ExperimentDataWarehouseNode with its own math and math_property — the math determines how each side is aggregated before the ratio is taken.

Use for revenue per pageview, click-through rate, error rate, engagement ratios.

Right — click-through rate (count / count)

{
  "kind": "ExperimentMetric",
  "metric_type": "ratio",
  "name": "Click-through rate",
  "numerator": {
    "kind": "EventsNode",
    "event": "button_clicked"
  },
  "denominator": {
    "kind": "EventsNode",
    "event": "$pageview"
  }
}

Right — revenue per pageview (sum of property / count)

To divide a property sum by an event count, the numerator's math is "sum" and math_property names the numeric property to sum. The denominator stays at the default count.

{
  "kind": "ExperimentMetric",
  "metric_type": "ratio",
  "name": "Revenue per pageview",
  "numerator": {
    "kind": "EventsNode",
    "event": "purchase_completed",
    "math": "sum",
    "math_property": "revenue"
  },
  "denominator": {
    "kind": "EventsNode",
    "event": "$pageview"
  }
}

Wrong — is_set filter instead of math / math_property

{
  "kind": "ExperimentMetric",
  "metric_type": "ratio",
  "name": "Revenue per pageview",
  "numerator": {
    "kind": "EventsNode",
    "event": "purchase_completed",
    "properties": [
      { "key": "revenue", "value": "is_set", "operator": "is_set", "type": "event" }
    ]
  },
  "denominator": { "kind": "EventsNode", "event": "$pageview" }
}

A property filter scopes which events count — it does not sum them. The numerator above counts purchases that have a revenue property, not the revenue total. Aggregation lives in math / math_property, never in a filter.

Retention metric

Whether users return after initial exposure. Tracks start_event → completion_event over a window defined by retention_window_start, retention_window_end, and retention_window_unit. start_handling is required and controls how users with multiple start events are anchored: "first_seen" (anchor on first occurrence) or "last_seen" (anchor on most recent).

The window is measured from the start event and bucketed by retention_window_unit, which is "day" or "hour". The start occurrence never counts as its own completion — only a distinct later event does — so the start and completion events may be the same:

  • Different events (e.g. $pageview → uploaded_file) — conversion retention: "did the user reach the target action within the window?"
  • Same event (e.g. nav_panel_clicked → nav_panel_clicked) — repeat retention: "did the user fire it again within the window?" From 0 counts a repeat from the same period onward (same-day/same-hour repeats count); From N (N ≥ 1) requires the repeat in a later period. Use start_handling: "first_seen" so in-experiment repeats fall after the anchor — last_seen anchors on the user's final occurrence, which has no in-experiment activity after it.

Right — conversion retention (different events)

{
  "kind": "ExperimentMetric",
  "metric_type": "retention",
  "name": "7-day file-upload retention",
  "start_event": {
    "kind": "EventsNode",
    "event": "$pageview"
  },
  "completion_event": {
    "kind": "EventsNode",
    "event": "uploaded_file"
  },
  "retention_window_start": 0,
  "retention_window_end": 7,
  "retention_window_unit": "day",
  "start_handling": "first_seen"
}

Right — repeat retention (same event)

{
  "kind": "ExperimentMetric",
  "metric_type": "retention",
  "name": "7-day repeat-click retention",
  "start_event": {
    "kind": "EventsNode",
    "event": "nav_panel_clicked"
  },
  "completion_event": {
    "kind": "EventsNode",
    "event": "nav_panel_clicked"
  },
  "retention_window_start": 0,
  "retention_window_end": 7,
  "retention_window_unit": "day",
  "start_handling": "first_seen"
}

Measures "of users who clicked the promoted product, how many clicked it again within 7 days". The first click anchors the window and never counts as its own completion — only a later distinct click does, so a one-time clicker is correctly counted as not retained.

Wrong — missing retention_window_start and start_handling

{
  "kind": "ExperimentMetric",
  "metric_type": "retention",
  "name": "7-day retention",
  "start_event": { "kind": "EventsNode", "event": "$pageview" },
  "completion_event": { "kind": "EventsNode", "event": "uploaded_file" },
  "retention_window_end": 7,
  "retention_window_unit": "day"
}

Pydantic rejects the payload with a missing-field error. Both fields are required on every retention metric — the schema is the source of truth.

Adding metrics to an experiment

A metric reaches an experiment via one of two independent experiment-update fields. Attaching a shared metric does not touch the inline metrics array, and vice versa.

Inline metric — metrics

Call experiment-update with the full metrics array. This replaces the entire inline list.

To add a metric without losing existing ones:

  1. Call experiment-get to get current metrics
  2. Append the new metric to the existing array
  3. Call experiment-update with the combined array

Shared (saved) metric — saved_metrics_ids

Reuse a metric that already exists in the project instead of duplicating it inline. Resolve the id with experiment-saved-metrics-list, then attach it:

  1. Call experiment-saved-metrics-list to find the metric and its id (pass a search term to resolve by name; results are paginated, so use limit/offset when browsing a large project)
  2. Call experiment-get to read the experiment's current saved_metrics
  3. Call experiment-update with saved_metrics_ids — this replaces all existing saved-metric links, so send the full desired set:
{
  "saved_metrics_ids": [
    { "id": 42, "metadata": { "type": "primary" } },
    { "id": 57, "metadata": { "type": "secondary" } }
  ]
}

The id here is the saved-metric id. Note the read/write asymmetry when you rebuild the set from experiment-get: each entry in the returned saved_metrics exposes a top-level id (the link row) and a separate saved_metric (the metric id). Map each existing entry's saved_metric into the id you resend — sending the link id attaches the wrong metric or fails validation.

metadata is optional and defaults to primary. Pass an empt