Pipeline API concepts

What the building blocks mean and how they fit together. For field tables and endpoints, use the API reference. For hands-on steps, see the Quickstart or Building a custom pipeline.

---

Two kinds of questions

Pipelines run over generic events. To read those rows without aggregating them, see Retrieving events. A definition answers:

1. Counts — How many distinct visitors / sessions / events matched each stage in a period?
2. Occupancy (last-state) — Where is each entity now (which stage holds its newest matching event)?

Pipeline definition
│
├── step 0: "Widget started"   → visitors with category=widget, action=start
├── step 1: "Widget clicked"   → visitors with category=widget, action=click
└── step 2: "Goals reached"    → visitors with category=goal, action=trigger

On counts, steps are independent: matching step 0 is not required to count in step 2.

On last-state, the same steps are buckets. An entity appears in at most one of them (newest match by collector_created_at, then event_id).

Optional features on top:

• Metrics — breakdowns inside a step (e.g. visitors by goal)
• Dimensions — slice all step counts at query time without editing the definition
• Value sets — named ID lists ($interaction-ids) so definitions stay stable when the ID list changes

---

Steps and filters

Each step has:

• count_field — what counts distinctly on /counts (visitor_id, session_id, event_id, or dim1–dim5)
• events — filters; fields in one filter are AND-ed, filters are OR-ed
• optional metrics
• optional identity_field on each event — entity key for last-state only

{ "category": "widget", "action": ["openchat", "leadform", "starttask"], "label": "$interaction-ids" }

Full field rules: Event filters.

---

Counts vs last-state

	Counts	Last-state
Question	How many matched each step?	Where is each entity now?
Key	Step count_field	Event identity_field
Same entity in several steps	Yes	No — newest match wins
Metrics / dimension filters	Yes (metrics via step-detail)	No

Use last-state when you care about current workload (e.g. cases sitting in each stage). Use counts when you care about volume or conversion across stages.

/last-state-detail lists the identities in one step (the full list today; pagination is coming soon). include_inactive + lookback_start also count entities that did not move during the active window (lookback up to 365 days).

Endpoint details: Query endpoints.

---

Value sets

Named lists of strings per organization. The same pipeline can mean different ID sets for different orgs because $interaction-ids resolves at query time.

If a referenced value set is missing, that filter field is unconstrained.

---

Metrics

Extra aggregations on a step, returned only by step-detail. A step’s count answers “how many?”; a metric answers “how were they split?” or “what was the total?”.

Configured with measure, optional group_by, optional mapping_functions (IDs → names), and optional display hints (units, display_names, group_by_display_names, single_period).

Metrics reference

---

Dimensions

Dimensions let you filter a multi-step pipeline by one logical property even when:

1. The same idea lives in different fields on different event types (widget label = interaction ID; goal label = goal ID), or
2. A step’s events don’t carry the property at all — you inherit matching sessions from another step (cohort).

At definition time you map each step (field or cohort_from_step). At query time you pass values once.

Partial dimensions cover only some steps. Combining several partials (e.g. interactions on widget steps + goals on the goal step) is a common “filter by project” pattern.

Dimensions reference

---

Query-time filters

• base_filters — global (country, city, rooms). Also used on last-state.
• filters — named dimensions. Counts and step-detail only (not last-state).

Both can optionally apply to pageview counts when you request them.

Filters reference

---

Annotated definition example

{
  "name": "Impressions to goals (filtered)",
  "steps": [
    {
      "name": "Impressions",
      "count_field": "visitor_id",
      "events": [
        { "category": "widget", "action": "start", "label": "$interaction-ids" }
      ],
      "metrics": [
        {
          "name": "Impressions by interaction",
          "measure": { "field": "visitor_id", "aggregations": ["count_distinct"] },
          "group_by": ["label"],
          "mapping_functions": { "label": "f$interactions" }
        }
      ]
    },
    {
      "name": "Engaged with giosg",
      "count_field": "visitor_id",
      "events": [
        { "category": "widget", "action": "click", "label": "$interaction-ids" }
      ]
    },
    {
      "name": "Goals reached",
      "count_field": "visitor_id",
      "events": [
        { "category": "goal", "action": "trigger", "label": "$goal-ids" }
      ],
      "metrics": [
        {
          "name": "Users by goal",
          "measure": { "field": "visitor_id", "aggregations": ["count_distinct"] },
          "group_by": ["label"],
          "mapping_functions": { "label": "f$goals" }
        }
      ]
    }
  ],
  "dimensions": [
    {
      "name": "interaction",
      "label": "Interaction",
      "step_mappings": [
        { "step_index": 0, "field": "label" },
        { "step_index": 1, "field": "label" },
        { "step_index": 2, "cohort_from_step": 0 }
      ]
    },
    {
      "name": "goal",
      "label": "Goal",
      "partial": true,
      "step_mappings": [
        { "step_index": 2, "field": "label" }
      ]
    }
  ]
}

---

Next

Goal	Guide
Predefined counts quickly	Quickstart
Create / sync a pipeline	Building a custom pipeline
Case funnel variants	Choosing a funnel variant
Slice counts	Filtering
API contracts	Pipeline API reference