Skip to content

Query endpoints

These three endpoints run queries against pipeline data. They do not modify any stored resources.

Pipeline counts

Runs a pipeline definition over a date range and returns the count for each step. Value set references are resolved for the requesting organization at query time.

Endpoint

POST https://api.giosg.com/api/objectives/v1/orgs/<organization_id>/pipeline/counts

Payload

Attribute Type Description
pipeline_id uuid ID of the pipeline definition to run. Required.
start string Start of date range (ISO-8601 datetime). Required.
end string End of date range (ISO-8601 datetime). Required. Must be after start.
include_pageview_counts boolean If true, also returns visitor counts from the pageview table. Default false.
base_filters array Global pre-filters applied to all steps. Default []. Each item: { "field": string, "values": [string, ...], "apply_to_pageview": bool }. Supported fields: geo_city, geo_country, room_ids. See Filters.
filters array Active dimension filters. Default []. Each item: { "dimension_name": string, "values": [string, ...], "apply_to_pageview": bool }. See Filters.

Minimal example — just a date range:

1
2
3
4
5
{
  "pipeline_id": "a1b2c3d4-e5f6-7890-abcd-ef1234567890",
  "start": "2024-01-01T00:00:00Z",
  "end": "2024-01-31T23:59:59Z"
}

Example with filters — base_filters pre-filter all steps by a raw event field; filters reference a named dimension declared on the pipeline definition (e.g. interaction)

 1
 2
 3
 4
 5
 6
 7
 8
 9
10
11
12
{
  "pipeline_id": "a1b2c3d4-e5f6-7890-abcd-ef1234567890",
  "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 }
  ]
}

Response

Attribute Type Description
pipeline_id string UUID of the pipeline definition.
pipeline_name string Name of the pipeline definition.
organization_id string Organization UUID.
start_date string Start of range used (ISO-8601). e.g. "2024-01-01T00:00:00".
end_date string End of range used (ISO-8601).
steps array List of step result objects (see below).
pageview_counts object Present only when include_pageview_counts: true (see below).

Each element in steps:

Attribute Type Description
step_name string Name of the step.
count number Distinct count of the step's count_field matching the step's filters in the period.

pageview_counts object:

Attribute Type Description
visitor_count number Total distinct visitors from the pageview table in the date range.
by_source array List of { "source": string, "visitor_count": number } broken down by the source field.
source_field string The pageview column used as the source dimension (from pageview_source_field on the definition; defaults to referrer_medium).

Example response:

 1
 2
 3
 4
 5
 6
 7
 8
 9
10
11
12
13
14
15
16
17
18
19
{
  "pipeline_id": "a1b2c3d4-e5f6-7890-abcd-ef1234567890",
  "pipeline_name": "Widget engagement",
  "organization_id": "...",
  "start_date": "2024-01-01T00:00:00.000",
  "end_date": "2024-01-31T23:59:59.000",
  "steps": [
    { "step_name": "Widget started", "count": 1250 },
    { "step_name": "Widget clicked", "count": 480  }
  ],
  "pageview_counts": {
    "visitor_count": 5000,
    "by_source": [
      { "source": "organic", "visitor_count": 2100 },
      { "source": "direct",  "visitor_count": 1800 }
    ],
    "source_field": "referrer_medium"
  }
}

Pipeline step detail

Returns the count for a single step plus the results of any metrics defined on that step. Use this to get a deeper breakdown of one step. What you get here would depend on the step's definition and any metrics defined on it.

Endpoint

POST https://api.giosg.com/api/objectives/v1/orgs/<organization_id>/pipeline/step-detail

Payload

Attribute Type Description
pipeline_id uuid ID of the pipeline definition. Required.
step_index integer Zero-based index of the step to inspect (≥ 0). Required.
start string Start of date range (ISO-8601 datetime). Required.
end string End of date range (ISO-8601 datetime). Required. Must be after start.
base_filters array Global pre-filters. Same shape as in Pipeline counts.
filters array Active dimension filters. Same shape as in Pipeline counts.

Example:

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

Response

Attribute Type Description
pipeline_id string UUID of the pipeline definition.
pipeline_name string Name of the pipeline definition.
step_index number Zero-based index of the step returned.
step object Full step definition (name, count_field, events, metrics).
organization_id string Organization UUID.
start_date string Start of range used (ISO-8601).
end_date string End of range used (ISO-8601).
data object Result data (see below).

data object:

Attribute Type Description
count number Distinct count for the step's count_field matching the step's event filters.
metric_name array For each metric on the step: a list of row objects. Column names depend on group_by fields and aggregations.

Example response:

 1
 2
 3
 4
 5
 6
 7
 8
 9
10
11
12
13
14
15
16
17
18
19
20
21
22
23
24
{
  "pipeline_id": "00000000-0000-0000-0000-000000000001",
  "pipeline_name": "Impression Pipeline",
  "step_index": 2,
  "step": {
    "name": "Positive outcome",
    "count_field": "visitor_id",
    "events": [ { "category": "widget", "action": [...], "label": "$interaction-ids" } ],
    "metrics": [
      {
        "name": "Users by action",
        "measure": { "field": "visitor_id", "aggregations": ["count_distinct"] },
        "group_by": ["action"]
      }
    ]
  },
  "data": {
    "count": 120,
    "Users by action": [
      { "action": "openchat",  "count_distinct_visitor_id": 75 },
      { "action": "leadform",  "count_distinct_visitor_id": 45 }
    ]
  }
}

If the step has no metrics, data only contains count. When mapping_functions are configured on a metric, raw ID values in the grouped column are translated to human-readable names before the response is returned.

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

List event dimensions

Returns distinct (vendor, category, action) combinations from generic events in a date range. Use this to discover valid filter values when building pipeline steps.

Endpoint

POST https://api.giosg.com/api/objectives/v1/orgs/<organization_id>/pipeline/events

Payload

Attribute Type Description
start string Start of date range (ISO-8601 datetime). Required.
end string End of date range (ISO-8601 datetime). Required. Must be after start.
include_blacklisted_categories boolean If true, includes internal/system event categories. Default false.

Example:

1
2
3
4
{
  "start": "2024-01-01T00:00:00Z",
  "end": "2024-01-31T23:59:59Z"
}

Response

Attribute Type Description
organization_id string Organization UUID.
start_date string Start of range used (ISO-8601).
end_date string End of range used (ISO-8601).
include_blacklisted_categories boolean Whether internal categories were included.
count number Number of distinct (vendor, category, action) combinations.
events array List of objects with vendor, category, action.