Skip to content

Filtering counts and drilling into steps

Filters are passed in the request body at query time — no changes to your pipeline definition are needed. Two types are available:

  • base_filters — a global pre-filter applied to all steps (e.g. restrict to one country).
  • filters — dimension-specific filters that use dimensions declared on the pipeline definition.

Both types work on the counts endpoint and the step-detail endpoint, and both support apply_to_pageview to also restrict pageview visitor counts.

The examples below use the predefined Impression Pipeline (00000000-0000-0000-0000-000000000001), which already has interaction, goal, interactions_only, and goals_only dimensions defined. You can run these against your own organization immediately. For custom pipelines, see Building a custom pipeline — dimensions.

Using base filters

Base filters restrict the event pool for all steps before any step-specific matching. Supported fields: geo_country, geo_city, room_ids.

Example — restrict all steps to Finnish visitors:

 1
 2
 3
 4
 5
 6
 7
 8
 9
10
11
12
13
POST https://api.giosg.com/api/objectives/v1/orgs/<organization_id>/pipeline/counts
Content-Type: application/json
Authorization: Bearer <token>

{
  "pipeline_id": "00000000-0000-0000-0000-000000000001",
  "start": "2024-01-01T00:00:00Z",
  "end": "2024-01-31T23:59:59Z",
  "include_pageview_counts": true,
  "base_filters": [
    { "field": "geo_country", "values": ["FI"], "apply_to_pageview": true }
  ]
}

Using dimension filters

Dimension filters reference a named dimension declared on the pipeline definition. Each step is filtered according to its mapping in that dimension: steps with a direct field mapping are filtered on that field; steps with a cohort_from_step mapping inherit the matching sessions from the source step.

Example — filter by interaction ID using the interaction dimension (steps 0–2 filter directly on label; step 3 inherits matching sessions via cohort):

 1
 2
 3
 4
 5
 6
 7
 8
 9
10
11
12
POST https://api.giosg.com/api/objectives/v1/orgs/<organization_id>/pipeline/counts
Content-Type: application/json
Authorization: Bearer <token>

{
  "pipeline_id": "00000000-0000-0000-0000-000000000001",
  "start": "2024-01-01T00:00:00Z",
  "end": "2024-01-31T23:59:59Z",
  "filters": [
    { "dimension_name": "interaction", "values": ["int-abc-123"], "apply_to_pageview": true }
  ]
}

Using an unknown dimension_name returns 400.

Combining base filters and dimension filters

base_filters and filters can be used together in the same request. They are independent — base filters narrow by raw event fields, dimension filters apply the dimension's per-step logic on top of that.

 1
 2
 3
 4
 5
 6
 7
 8
 9
10
11
12
13
14
15
16
POST https://api.giosg.com/api/objectives/v1/orgs/<organization_id>/pipeline/counts
Content-Type: application/json
Authorization: Bearer <token>

{
  "pipeline_id": "00000000-0000-0000-0000-000000000001",
  "start": "2024-01-01T00:00:00Z",
  "end": "2024-01-31T23:59:59Z",
  "include_pageview_counts": true,
  "base_filters": [
    { "field": "geo_country", "values": ["FI"], "apply_to_pageview": true }
  ],
  "filters": [
    { "dimension_name": "interaction", "values": ["int-abc-123"], "apply_to_pageview": true }
  ]
}

apply_to_pageview defaults to true if omitted. Multiple filters entries are AND-ed.

Filtering by project with partial dimensions

When a pipeline defines multiple partial dimensions that together cover all steps, you can pass all of them in one request to act as a single compound filter.

Example — the Impression Pipeline has interactions_only (partial, steps 0–2) and goals_only (partial, step 3). Passing both populated with IDs from one project filters the entire 4-step pipeline "by project":

 1
 2
 3
 4
 5
 6
 7
 8
 9
10
11
12
13
POST https://api.giosg.com/api/objectives/v1/orgs/<organization_id>/pipeline/counts
Content-Type: application/json
Authorization: Bearer <token>

{
  "pipeline_id": "00000000-0000-0000-0000-000000000001",
  "start": "2024-01-01T00:00:00Z",
  "end": "2024-01-31T23:59:59Z",
  "filters": [
    { "dimension_name": "interactions_only", "values": ["int-aaa", "int-bbb"] },
    { "dimension_name": "goals_only",        "values": ["goal-zzz"] }
  ]
}

Steps 0–2 are restricted to the project's interaction IDs; step 3 is restricted to the project's goal IDs. Steps not covered by a partial dimension are unaffected by that filter entry.

Drilling into a step with step-detail

The step-detail endpoint returns the count for a single step plus the results of any metrics defined on it. Use this to understand what's happening inside a specific funnel stage.

 1
 2
 3
 4
 5
 6
 7
 8
 9
10
POST https://api.giosg.com/api/objectives/v1/orgs/<organization_id>/pipeline/step-detail
Content-Type: application/json
Authorization: Bearer <token>

{
  "pipeline_id": "00000000-0000-0000-0000-000000000001",
  "step_index": 3,
  "start": "2024-01-01T00:00:00Z",
  "end": "2024-01-31T23:59:59Z"
}

step_index is zero-based (0 = first step). Works for both custom and predefined pipelines.

Response:

 1
 2
 3
 4
 5
 6
 7
 8
 9
10
11
12
13
14
15
16
17
18
{
  "pipeline_id": "00000000-0000-0000-0000-000000000001",
  "pipeline_name": "Impression Pipeline",
  "step_index": 3,
  "step": {
    "name": "Goals reached",
    "count_field": "visitor_id",
    "events": [ ... ],
    "metrics": [ ... ]
  },
  "data": {
    "count": 42,
    "Users by goal": [
      { "label": "My first goal",  "count_distinct_visitor_id": 25 },
      { "label": "My second goal", "count_distinct_visitor_id": 17 }
    ]
  }
}

data.count is the step count. Each metric defined on the step appears as an additional key in data (named after the metric's name field). If mapping_functions are configured, raw IDs in the grouped column are translated to human-readable names before the response is returned.

If the step has no metrics, data only contains count. If the step has metrics but no matching events in the requested range, every metric key is an empty array [] — including ungrouped metrics (no group_by).

Passing filters to step-detail

The same filters and base_filters fields are accepted by step-detail. The step count and all metric results reflect only events matching the active filters:

1
2
3
4
5
6
7
8
9
{
  "pipeline_id": "00000000-0000-0000-0000-000000000001",
  "step_index": 3,
  "start": "2024-01-01T00:00:00Z",
  "end": "2024-01-31T23:59:59Z",
  "filters": [
    { "dimension_name": "interaction", "values": ["int-abc-123"], "apply_to_pageview": false }
  ]
}

Returns 400 if step_index is out of range, 404 if the pipeline is not found.

Next steps