Object reference¶

Field-level reference for the objects used in pipeline definitions and queries: event filters, metrics, dimensions, and query-time filters.

For the reasoning behind these objects and when to use each one, see Concepts.

Event filters¶

One object inside a step's events list. At least one field must be present; omitted fields place no restriction.

Matching rules

Fields within a single filter object are AND-ed.
Multiple filter objects on a step are OR-ed: the step matches a row if any object matches.

Use a list value when objects would differ only by one field's value; use multiple objects when the field combinations differ:

{
  "name": "Positive outcome",
  "events": [
    { "category": "widget", "action": ["openchat", "leadform", "starttask"], "label": "$interaction-ids" },
    { "category": "goal", "action": "trigger", "label": "$goal-ids" }
  ]
}

Filter fields¶

Field	Type	Semantics
`vendor`	string, list, or value set reference	Exact match, or match any value in the list.
`category`	string, list, or value set reference	Exact match, or match any value in the list.
`action`	string, list, or value set reference	Exact match, or match any value in the list.
`label`	string, list, or value set reference	Exact match, or match any value in the list.
`room_ids`	string, list, or value set reference	Matches if any of the event's room IDs appear in the filter list. Room IDs are parsed from `properties` entries of the form `room_id=…` (not a stored column).
`properties`	list of `"key=value"` strings	All listed entries must be present on the event. No value set references.
`identity_field`	string	Optional entity key for last-state. One of `visitor_id`, `session_id`, `user_id`, `dim1`–`dim5` (not `event_id`). Ignored by counts.

Value set references¶

vendor, category, action, label, and room_ids accept a reference to a value set: a string starting with $. The reference resolves to the requesting organization's list at query time.

Form	Example
String	`"action": "click"`
List of strings	`"action": ["start", "click"]`
Value set reference	`"label": "$interaction-ids"`

If the referenced value set does not exist, that field places no restriction on the step.

Identity field¶

Used only by last-state, as the entity key for the events it is set on. It is not a match condition, and it is separate from the step's count_field.

/last-state requires it on every event of every step; definitions meeting that condition report supports_last_state: true.
Events in the same step may use different identity fields and still count toward that step.
Case-funnel sync sets identity_field: dim3 (case number) only on the Case status snapshot variant.

{
  "category": "case_management",
  "action": "step_started",
  "label": "<case_funnel_stage_id>",
  "identity_field": "dim3"
}

The `properties` field¶

A list of "key=value" strings; every entry must be present on the event.

{
  "category": "shopping-cart",
  "action": "purchased",
  "properties": ["with_real_conversation=true", "currency=EUR"]
}

Metrics¶

Optional aggregations attached to a step. Returned by step-detail only — counts and last-state ignore them.

Metric object¶

Attribute	Type	Description
`name`	string	Optional label. Used as the key for this metric in the step-detail `data` response.
`measure`	object	Required. What to aggregate — see Measure.
`group_by`	array	Event fields to group by. Empty or omitted produces a single aggregate row.
`group_by_display_names`	array \| null	Optional display labels, aligned with `group_by` (same length).
`mapping_functions`	object	Optional. Maps `group_by` field names to ID-to-name translations. Every key must also appear in `group_by`.
`single_period`	boolean	Optional; default `false`. When `true`, clients should show a single value rather than a period-over-period comparison.

Empty results

When a step has no matching events in the requested range, every metric in the step-detail data response is an empty array [] — including ungrouped aggregates.

Measure¶

Attribute	Type	Description
`field`	string	Event field to aggregate. Required.
`aggregations`	array	Non-empty list of aggregation functions. Required.
`units`	array \| null	Optional display units, aligned with `aggregations` (same length). Use `""` for an aggregation with no unit.
`display_names`	array \| null	Optional display labels, aligned with `aggregations` (same length).

Supported fields and aggregations

Field	Allowed aggregations
`event_id`	`count`, `count_distinct`
`visitor_id`	`count`, `count_distinct`
`session_id`	`count`, `count_distinct`
`user_id`	`count`, `count_distinct`
`value`	`count`, `count_distinct`, `sum`, `avg`, `min`, `max`
`dim1`–`dim5`	`count`, `count_distinct`, `sum`, `avg`, `min`, `max`

Multiple aggregations on one field produce one row with a column per aggregation:

{
  "name": "Cart value",
  "measure": {
    "field": "value",
    "aggregations": ["sum", "avg"],
    "display_names": ["Total", "Average"]
  }
}

Result row: { "sum_value": 14200.0, "avg_value": 142.0 }

With units, for duration-style metrics:

{
  "name": "Duration total",
  "measure": {
    "field": "value",
    "aggregations": ["sum", "avg", "min", "max"],
    "units": ["s", "s", "s", "s"],
    "display_names": ["Total", "Average", "Min", "Max"]
  }
}

group_by¶

Produces one row per distinct combination of the listed field values.

Supported fields: action, category, label, vendor, room_ids, dim1–dim5, geo_country, geo_city, device_type, browser_name, os_name

{
  "name": "Visitors by country and device",
  "measure": { "field": "visitor_id", "aggregations": ["count_distinct"] },
  "group_by": ["geo_country", "device_type"]
}

[
  { "geo_country": "FI", "device_type": "desktop", "count_distinct_visitor_id": 320 },
  { "geo_country": "FI", "device_type": "mobile",  "count_distinct_visitor_id": 180 },
  { "geo_country": "SE", "device_type": "desktop", "count_distinct_visitor_id": 95  }
]

mapping_functions¶

Translates opaque IDs in a group_by column (such as goal or interaction IDs in label) into readable names in step-detail results. Unknown IDs are returned unchanged.

"mapping_functions": { "label": "f$goals" }

Function ID	Translates
`f$goals`	Goal IDs → goal names
`f$interactions`	Interaction IDs → interaction names

Before: { "label": "goal-abc-123", "count_distinct_visitor_id": 42 }
After: { "label": "Newsletter signup", "count_distinct_visitor_id": 42 }

Dimensions¶

A dimension declares how one logical property (interaction, goal, city, …) maps onto each step, so a single query-time filter value can be applied correctly per step. See Dimensions for the reasoning.

Dimension object¶

Attribute	Type	Description
`name`	string	Unique within the pipeline. Required. Referenced by `dimension_name` in query filters.
`label`	string	Optional display label.
`partial`	boolean	If `true`, covers only the listed steps. Default `false`.
`step_mappings`	array	Required. One entry per step (full), or per covered step (partial).
`pageview_cohort_from_step`	integer	Optional. Step whose matching sessions filter pageview counts. Not allowed on partial dimensions.

Step mappings¶

Each entry applies the dimension to one step. Exactly one of field or cohort_from_step is required per entry.

Attribute	Type	Description
`step_index`	integer	Zero-based step index. Required.
`field`	string	Filter this step directly on the named event field. Mutually exclusive with `cohort_from_step`.
`cohort_from_step`	integer	Restrict this step to sessions that matched the filter on the referenced step. That step must use a direct `field` mapping in the same dimension. Mutually exclusive with `field`.

Supported field values: action, category, label, vendor, room_ids, dim1–dim5, geo_country, geo_city, device_type, browser_name, os_name

Direct mapping — every step carries the value in the same field:

{
  "name": "interaction",
  "label": "Interaction",
  "step_mappings": [
    { "step_index": 0, "field": "label" },
    { "step_index": 1, "field": "label" }
  ],
  "pageview_cohort_from_step": 0
}

Cohort mapping — step 2 holds goal IDs in label, so it cannot filter by interaction ID directly and inherits matching sessions from step 0 instead:

{
  "name": "interaction",
  "label": "Interaction",
  "step_mappings": [
    { "step_index": 0, "field": "label" },
    { "step_index": 1, "field": "label" },
    { "step_index": 2, "cohort_from_step": 0 }
  ],
  "pageview_cohort_from_step": 0
}

The reverse direction works the same way — the goal step maps directly and the widget steps take a cohort from it:

{
  "name": "goal",
  "label": "Goal",
  "step_mappings": [
    { "step_index": 0, "cohort_from_step": 2 },
    { "step_index": 1, "cohort_from_step": 2 },
    { "step_index": 2, "field": "label" }
  ]
}

Cohort isolation

A cohort source step is evaluated using only the dimension that defines the cohort. Other active dimension filters do not affect it.

Partial dimensions¶

With "partial": true, the dimension covers only the steps listed in step_mappings; all other steps are unaffected when it is used as a filter. Combining several partial dimensions that together cover every step gives you one compound filter (for example, interaction IDs on widget steps and goal IDs on the goal step):

[
  {
    "name": "interaction",
    "label": "Interaction",
    "partial": true,
    "step_mappings": [
      { "step_index": 0, "field": "label" },
      { "step_index": 1, "field": "label" }
    ]
  },
  {
    "name": "goal",
    "label": "Goal",
    "partial": true,
    "step_mappings": [
      { "step_index": 2, "field": "label" }
    ]
  }
]

Both can then be passed in one request:

"filters": [
  { "dimension_name": "interaction", "values": ["int-aaa", "int-bbb"] },
  { "dimension_name": "goal",        "values": ["goal-zzz"] }
]

Rules for partial dimensions

At least one step_mapping.
step_index values unique and within [0, N-1].
Direct field mappings only — no cohort_from_step.
pageview_cohort_from_step not allowed.

Validation rules (full dimensions)¶

Exactly one step_mappings entry per step (step_index values 0, 1, …, N-1).
field and cohort_from_step are mutually exclusive per entry.
A cohort_from_step source must have a direct field mapping in the same dimension.
pageview_cohort_from_step must reference a step with a direct field mapping in the same dimension.
Dimension names must be unique within the pipeline.

Filters¶

Passed in the request body of counts, last-state, or step-detail. They do not change the definition.

Counts / step-detail: base_filters and dimension filters.
Last-state: base_filters only — a non-empty dimension filters list returns 400.

Base filters¶

Global pre-filter applied to all steps. On last-state, applied before each entity's newest event is selected.

Attribute	Type	Description
`field`	string	One of `geo_city`, `geo_country`, `room_ids`. Required.
`values`	array	Non-empty list of strings. Required.
`apply_to_pageview`	boolean	Also apply when pageview counts are requested. Default `true`. Ignored by last-state.

Multiple entries are AND-ed.

"base_filters": [
  { "field": "geo_country", "values": ["FI", "SE"] },
  { "field": "geo_city", "values": ["Helsinki"], "apply_to_pageview": false }
]

Active dimension filters¶

References a dimension declared on the pipeline and restricts each step according to that dimension's mapping. Direct-mapped steps filter on the field; cohort-mapped steps are restricted to sessions that matched on the source step.

Attribute	Type	Description
`dimension_name`	string	Name of a dimension on the pipeline. Required. Unknown names return `400`.
`values`	array	Non-empty list of strings. Required.
`apply_to_pageview`	boolean	Also restrict pageview counts, via `pageview_cohort_from_step`. Default `true`.