Pipeline API¶
The Pipeline API lets you define multi-step analytics pipelines over event data, run counts per step for a date range, and drill into per-step metrics.
Base URL: https://api.giosg.com/api/objectives/v1/orgs/<organization_id>/pipeline
Authentication: standard API Bearer token. The URL organization_id must match the authenticated organization.
In this section¶
| Page | What it covers |
|---|---|
| Query endpoints | Counts, step-detail, and event dimensions endpoints |
| Managing definitions | Create, list, update, delete pipeline definitions; predefined pipelines |
| Managing value sets | Create, list, update, delete value sets |
| Object reference | Event filters, metrics, dimensions, filters — full field tables |
For tutorials and walkthroughs, see the Pipeline API tutorial section.
Concepts¶
| Term | Description |
|---|---|
| Pipeline definition | A named object with an ordered list of steps and optional dimensions. Describes what to measure. |
| Step | One measurement within a pipeline. Has a count field, one or more event filters, and optional metrics. |
| Count field | What each step counts distinctly: visitor_id (default), session_id, or event_id. |
| Event filter | A set of field conditions (vendor, category, action, label, room_ids, properties) that a row must satisfy to match a step. Multiple filters per step are OR-ed. |
| Value set | A named list of strings per organization, referenced in event filters as $name and resolved at query time. |
| Metric | An optional sub-query on a step that returns grouped aggregations. Evaluated by step-detail only. |
| Dimension | A named attribute declared on a pipeline that maps a filterable property (e.g. geo_city) to each step. Enables query-time slicing without modifying the definition. |
| Base filter | A global pre-filter applied to all steps before event matching. Supported fields: geo_country, geo_city, room_ids. |
| Active dimension filter | A query-time filter referencing a declared dimension by name. Restricts each step's count to matching events or sessions. |
| Pageview counts | Optional visitor counts from the pageview table, returned alongside step counts when include_pageview_counts: true. |
| Predefined pipeline | A global read-only pipeline available to all organizations, backed by a hardcoded server-side definition. |
Query behavior¶
- Time range: all steps use the same
startandend; events are filtered bycollector_created_at. - Step ordering: steps are stored with an explicit index and returned in the order they were created.
- Steps are independent: each step is counted separately — there is no funnel requirement that the same entity appears in earlier steps.
- OR within a step: a row matches a step if it matches any of the step's event filters.
- Metrics: evaluated only by the step-detail endpoint; ignored by the counts endpoint.
- Base filters: applied globally, narrowing the event pool for all steps. Available for all pipelines and steps (assuming these were correctly sent with the event as expected).
- Dimension filters: A filtering dimension definition, describing filtering logic for all or several steps. active dimension filter adds a per-step predicate. For direct-mapped steps, events must match the filter field. For cohort-mapped steps, only sessions that matched the filter on the source step are allowed through. Cohort sources are filtered only by the same dimension — other filters don't bleed in.
- Pageview filter propagation: filters with
apply_to_pageview: truealso restrict pageview counts. Base filters map to the pageview table's equivalent columns; dimension filters usepageview_cohort_from_step. - Value set resolution:
$namereferences in event filters are resolved at query time using the requesting organization's value sets. If the value set doesn't exist, the field adds no filter condition and the step is unconstrained on it.