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 0counts a repeat from the same period onward (same-day/same-hour repeats count);From N(N ≥ 1) requires the repeat in a later period. Usestart_handling: "first_seen"so in-experiment repeats fall after the anchor —last_seenanchors 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:
- Call
experiment-getto get current metrics - Append the new metric to the existing array
- Call
experiment-updatewith 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:
- Call
experiment-saved-metrics-listto find the metric and itsid(pass asearchterm to resolve by name; results are paginated, so uselimit/offsetwhen browsing a large project) - Call
experiment-getto read the experiment's currentsaved_metrics - Call
experiment-updatewithsaved_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