references/metric-configuration.md
Metric configuration
All metrics use kind: "ExperimentMetric". Legacy kinds (ExperimentTrendsQuery, ExperimentFunnelsQuery) are rejected.
The full Pydantic schema below is rendered from posthog/schema.py at build
time — if a field is missing here, fix the model. It is the ExperimentMetric
discriminated union: pick the variant matching your metric_type (mean,
funnel, ratio, retention) under $defs, and read that variant's
required array for the mandatory fields. The shared event-source building
blocks (EventsNode, ActionsNode, ExperimentDataWarehouseNode) and the
property-filter types are defined once under $defs and referenced by $ref.
The schema is authoritative; the prose and examples below are guidance.
Contents
- Schema
- Mean metric
- Funnel metric
- Ratio metric
- Retention metric
- Adding metrics to an experiment
- Property filters
Schema
{
"$defs": {
"AccountCustomPropertyFilter": {
"additionalProperties": false,
"properties": {
"key": {
"title": "Key",
"type": "string"
},
"label": {
"anyOf": [
{
"type": "string"
},
{
"type": "null"
}
],
"default": null,
"title": "Label"
},
"operator": {
"$ref": "#/$defs/PropertyOperator"
},
"type": {
"const": "account_custom_property",
"default": "account_custom_property",
"description": "Customer analytics account custom property \u2014 the key is the property definition id",
"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": "AccountCustomPropertyFilter",
"type": "object"
},
"ActionsNode": {
"additionalProperties": false,
"properties": {
"custom_name": {
"anyOf": [
{
"type": "string"
},
{
"type": "null"
}
],
"default": null,
"title": "Custom Name"
},
"fixedProperties": {
"anyOf": [
{
"items": {
"oneOf": [
{
"$ref": "#/$defs/EventPropertyFilter"
},
{
"$ref": "#/$defs/PersonPropertyFilter"
},
{
"$ref": "#/$defs/PersonMetadataPropertyFilter"
},
{
"$ref": "#/$defs/ElementPropertyFilter"
},
{
"$ref": "#/$defs/EventMetadataPropertyFilter"
},
{
"$ref": "#/$defs/SessionPropertyFilter"
},
{
"$ref": "#/$defs/CohortPropertyFilter"
},
{
"$ref": "#/$defs/RecordingPropertyFilter"
},
{
"$ref": "#/$defs/LogEntryPropertyFilter"
},
{
"$ref": "#/$defs/GroupPropertyFilter"
},
{
"$ref": "#/$defs/FeaturePropertyFilter"
},
{
"$ref": "#/$defs/FlagPropertyFilter"
},
{
"$ref": "#/$defs/HogQLPropertyFilter"
},
{
"$ref": "#/$defs/EmptyPropertyFilter"
},
{
"$ref": "#/$defs/DataWarehousePropertyFilter"
},
{
"$ref": "#/$defs/DataWarehousePersonPropertyFilter"
},
{
"$ref": "#/$defs/ErrorTrackingIssueFilter"
},
{
"$ref": "#/$defs/LogPropertyFilter"
},
{
"$ref": "#/$defs/MetricPropertyFilter"
},
{
"$ref": "#/$defs/SpanPropertyFilter"
},
{
"$ref": "#/$defs/RevenueAnalyticsPropertyFilter"
},
{
"$ref": "#/$defs/AccountCustomPropertyFilter"
},
{
"$ref": "#/$defs/WorkflowVariablePropertyFilter"
},
{
"$ref": "#/$defs/BehavioralPropertyFilter"
}
]
},
"type": "array"
},
{
"type": "null"
}
],
"default": null,
"description": "Fixed properties in the query, can't be edited in the interface (e.g. scoping down by person)",
"title": "Fixedproperties"
},
"id": {
"title": "Id",
"type": "integer"
},
"kind": {
"const": "ActionsNode",
"default": "ActionsNode",
"title": "Kind",
"type": "string"
},
"math": {
"anyOf": [
{
"$ref": "#/$defs/BaseMathType"
},
{
"$ref": "#/$defs/FunnelMathType"
},
{
"$ref": "#/$defs/PropertyMathType"
},
{
"$ref": "#/$defs/CountPerActorMathType"
},
{
"$ref": "#/$defs/GroupMathType"
},
{
"$ref": "#/$defs/ExperimentMetricMathType"
},
{
"$ref": "#/$defs/CalendarHeatmapMathType"
},
{
"const": "hogql",
"type": "string"
},
{
"type": "null"
}
],
"default": null,
"title": "Math"
},
"math_group_type_index": {
"anyOf": [
{
"$ref": "#/$defs/MathGroupTypeIndex"
},
{
"type": "null"
}
],
"default": null
},
"math_hogql": {
"anyOf": [
{
"type": "string"
},
{
"type": "null"
}
],
"default": null,
"title": "Math Hogql"
},
"math_multiplier": {
"anyOf": [
{
"type": "number"
},
{
"type": "null"
}
],
"default": null,
"title": "Math Multiplier"
},
"math_property": {
"anyOf": [
{
"type": "string"
},
{
"type": "null"
}
],
"default": null,
"title": "Math Property"
},
"math_property_revenue_currency": {
"anyOf": [
{
"$ref": "#/$defs/RevenueCurrencyPropertyConfig"
},
{
"type": "null"
}
],
"default": null
},
"math_property_type": {
"anyOf": [
{
"type": "string"
},
{
"type": "null"
}
],
"default": null,
"title": "Math Property Type"
},
"name": {
"anyOf": [
{
"type": "string"
},
{
"type": "null"
}
],
"default": null,
"title": "Name"
},
"optionalInFunnel": {
"anyOf": [
{
"type": "boolean"
},
{
"type": "null"
}
],
"default": null,
"title": "Optionalinfunnel"
},
"properties": {
"anyOf": [
{
"items": {
"oneOf": [
{
"$ref": "#/$defs/EventPropertyFilter"
},
{
"$ref": "#/$defs/PersonPropertyFilter"
},
{
"$ref": "#/$defs/PersonMetadataPropertyFilter"
},
{
"$ref": "#/$defs/ElementPropertyFilter"
},
{
"$ref": "#/$defs/EventMetadataPropertyFilter"
},
{
"$ref": "#/$defs/SessionPropertyFilter"
},
{
"$ref": "#/$defs/CohortPropertyFilter"
},
{
"$ref": "#/$defs/RecordingPropertyFilter"
},
{
"$ref": "#/$defs/LogEntryPropertyFilter"
},
{
"$ref": "#/$defs/GroupPropertyFilter"
},
{
"$ref": "#/$defs/FeaturePropertyFilter"
},
{
"$ref": "#/$defs/FlagPropertyFilter"
},
{
"$ref": "#/$defs/HogQLPropertyFilter"
},
{
"$ref": "#/$defs/EmptyPropertyFilter"
},
{
"$ref": "#/$defs/DataWarehousePropertyFilter"
},
{
"$ref": "#/$defs/DataWarehousePersonPropertyFilter"
},
{
"$ref": "#/$defs/ErrorTrackingIssueFilter"
},
{
"$ref": "#/$defs/LogPropertyFilter"
},
{
"$ref": "#/$defs/MetricPropertyFilter"
},
{
"$ref": "#/$defs/SpanPropertyFilter"
},
{
"$ref": "#/$defs/RevenueAnalyticsPropertyFilter"
},
{
"$ref": "#/$defs/AccountCustomPropertyFilter"
},
{
"$ref": "#/$defs/WorkflowVariablePropertyFilter"
},
{
"$ref": "#/$defs/BehavioralPropertyFilter"
}
]
},
"type": "array"
},
{
"type": "null"
}
],
"default": null,
"description": "Properties configurable in the interface",
"title": "Properties"
},
"response": {
"anyOf": [
{
"additionalProperties": true,
"type": "object"
},
{
"type": "null"
}
],
"default": null,
"title": "Response"
},
"version": {
"anyOf": [
{
"type": "number"
},
{
"type": "null"
}
],
"default": null,
"description": "version of the node, used for schema migrations",
"title": "Version"
}
},
"required": [
"id"
],
"title": "ActionsNode",
"type": "object"
},
"BaseMathType": {
"enum": [
"total",
"dau",
"weekly_active",
"monthly_active",
"unique_session",
"first_time_for_user",
"first_matching_event_for_user"
],
"title": "BaseMathType",
"type": "string"
},
"BehavioralEventSource": {
"enum": [
"events",
"actions"
],
"title": "BehavioralEventSource",
"type": "string"
},
"BehavioralPropertyFilter": {
"additionalProperties": false,
"properties": {
"event_filters": {
"anyOf": [
{
"items": {
"anyOf": [
{
"$ref": "#/$defs/EventPropertyFilter"
},
{
"$ref": "#/$defs/PersonPropertyFilter"
},
{
"$ref": "#/$defs/ElementPropertyFilter"
},
{
"$ref": "#/$defs/FeaturePropertyFilter"
},
{
"$ref": "#/$defs/HogQLPropertyFilter"
}
]
},
"type": "array"
},
{
"type": "null"
}
],
"default": null,
"description": "Extra property filters the matching events must satisfy. Deliberately excludes nested behavioral/cohort filters and groups",
"title": "Event Filters"
},
"event_type": {
"$ref": "#/$defs/BehavioralEventSource"
},
"explicit_datetime": {
"anyOf": [
{
"type": "string"
},
{
"type": "null"
}
],
"default": null,
"description": "Absolute or relative (e.g. -30d) lower date bound \u2014 alternative to time_value/time_interval",
"title": "Explicit Datetime"
},
"explicit_datetime_to": {
"anyOf": [
{
"type": "string"
},
{
"type": "null"
}
],
"default": null,
"title": "Explicit Datetime To"
},
"key": {
"description": "Event name, or action id when event_type is 'actions'",
"title": "Key",
"type": "string"
},
"label": {
"anyOf": [
{
"type": "string"
},
{
"type": "null"
}
],
"default": null,
"title": "Label"
},
"negation": {
"anyOf": [
{
"type": "boolean"
},
{
"type": "null"
}
],
"default": null,
"description": "Match persons who did NOT satisfy the criterion. Not the same as a low count \u2014 zero-occurrence persons never match count operators",
"title": "Negation"
},
"operator": {
"anyOf": [
{
"$ref": "#/$defs/PropertyOperator"
},
{
"type": "null"
}
],
"default": null,
"description": "Count comparison for performed_event_multiple, defaults to exact"
},
"operator_value": {
"anyOf": [
{
"type": "integer"
},
{
"type": "null"
}
],
"default": null,
"description": "Count threshold for performed_event_multiple",
"title": "Operator Value"
},
"time_interval": {
"anyOf": [
{
"$ref": "#/$defs/TimeUnitType"
},
{
"type": "null"
}
],
"default": null
},
"time_value": {
"anyOf": [
{
"type": "integer"
},
{
"type": "null"
}
],
"default": null,
"description": "Relative time window size, paired with time_interval",
"title": "Time Value"
},
"type": {
"const": "behavioral",
"default": "behavioral",
"description": "Person performed (or didn't perform) an event in a time window. ClickHouse-only \u2014 not evaluable by flags or CDP",
"title": "Type",
"type": "string"
},
"value": {
"$ref": "#/$defs/InlineBehavioralType"
}
},
"required": [
"event_type",
"key",
"value"
],
"title": "BehavioralPropertyFilter",
"type": "object"
},
"Breakdown": {
"additionalProperties": false,
"properties": {
"group_type_index": {
"anyOf": [
{
"type": "integer"
},
{
"type": "null"
}
],
"default": null,
"title": "Group Type Index"
},
"histogram_bin_count": {
"anyOf": [
{
"type": "integer"
},
{
"type": "null"
}
],
"default": null,
"title": "Histogram Bin Count"
},
"normalize_url": {
"anyOf": [
{
"type": "boolean"
},
{
"type": "null"
}
],
"default": null,
"title": "Normalize Url"
},
"property": {
"anyOf": [
{
"type": "string"
},
{
"type": "integer"
}
],
"title": "Property"
},
"type": {
"anyOf": [
{
"$ref": "#/$defs/MultipleBreakdownType"
},
{
"type": "null"
}
],
"default": null
}
},
"required": [
"property"
],
"title": "Breakdown",
"type": "object"
},
"BreakdownAttributionType": {
"enum": [
"first_touch",
"last_touch",
"all_events",
"step"
],
"title": "BreakdownAttributionType",
"type": "string"
},
"BreakdownFilter": {
"additionalProperties": false,
"properties": {
"breakdown": {
"anyOf": [
{
"type": "string"
},
{
"items": {
"anyOf": [
{
"type": "string"
},
{
"type": "integer"
}
]
},
"type": "array"
},
{
"type": "integer"
},
{
"type": "null"
}
],
"default": null,
"title": "Breakdown"
},
"breakdown_group_type_index": {
"anyOf": [
{
"type": "integer"
},
{
"type": "null"
}
],
"default": null,
"title": "Breakdown Group Type Index"
},
"breakdown_hide_other_aggregation": {
"anyOf": [
{
"type": "boolean"
},
{
"type": "null"
}
],
"default": null,
"title": "Breakdown Hide Other Aggregation"
},
"breakdown_histogram_bin_count": {
"anyOf": [
{
"type": "integer"
},
{
"type": "null"
}
],
"default": null,
"title": "Breakdown Histogram Bin Count"
},
"breakdown_limit": {
"anyOf": [
{
"type": "integer"
},
{
"type": "null"
}
],
"default": null,
"title": "Breakdown Limit"
},
"breakdown_normalize_url": {
"anyOf": [
{
"type": "boolean"
},
{
"type": "null"
}
],
"default": null,
"title": "Breakdown Normalize Url"
},
"breakdown_path_cleaning": {
"anyOf": [
{
"type": "boolean"
},
{
"type": "null"
}
],
"default": null,
"title": "Breakdown Path Cleaning"
},
"breakdown_type": {
"anyOf": [
{
"$ref": "#/$defs/BreakdownType"
},
{
"type": "null"
}
],
"default": "event"
},
"breakdowns": {
"anyOf": [
{
"items": {
"$ref": "#/$defs/Breakdown"
},
"maxItems": 3,
"type": "array"
},
{
"type": "null"
}
],
"default": null,
"title": "Breakdowns"
}
},
"title": "BreakdownFilter",
"type": "object"
},
"BreakdownType": {
"enum": [
"cohort",
"person",
"event",
"event_metadata",
"element",
"group",
"session",
"hogql",
"data_warehouse",
"data_warehouse_person_property",
"revenue_analytics"
],
"title": "BreakdownType",
"type": "string"
},
"CalendarHeatmapMathType": {
"enum": [
"total",
"dau"
],
"title": "CalendarHeatmapMathType",
"type": "string"
},
"CohortPropertyFilter": {
"additionalProperties": false,
"properties": {
"cohort_deleted": {
"anyOf": [
{
"type": "boolean"
},
{
"type": "null"
}
],
"default": null,
"description": "Set by the feature flag API when the cohort is deleted or does not exist.",
"title": "Cohort Deleted"
},
"cohort_missing": {
"anyOf": [
{
"type": "boolean"
},
{
"type": "null"
}
],
"default": null,
"description": "Set by the feature flag API when the cohort does not exist, so it cannot be restored.",
"title": "Cohort Missing"
},
"cohort_name": {
"anyOf": [
{
"type": "string"
},
{
"type": "null"
}
],
"default": null,
"title": "Cohort Name"
},
"key": {
"const": "id",
"default": "id",
"title": "Key",
"type": "string"
},
"label": {
"anyOf": [
{
"type": "string"
},
{
"type": "null"
}
],
"default": null,
"title": "Label"
},
"operator": {
"anyOf": [
{
"$ref": "#/$defs/PropertyOperator"
},