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.

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