Skip to content

Query endpoints

Run analytics against a saved pipeline definition. These endpoints do not create or modify definitions.

For conceptual differences between counts and occupancy, see Concepts. For listing raw event rows (not a pipeline run), see Event listing.

Pipeline counts

Returns one distinct count per step for a date range. Steps are independent (no ordering requirement between steps).

Endpoint

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

Payload

Attribute Type Description
pipeline_id uuid Pipeline definition to run. Required.
start string Inclusive start of collector_created_at (ISO-8601). Required.
end string Inclusive end of collector_created_at (ISO-8601). Required. Must be after start.
include_pageview_counts boolean If true, also returns visitor counts from pageviews. Default false.
base_filters array Global pre-filters. Default []. See Filters.
filters array Active dimension filters. Default []. See Filters. 
1
2
3
4
5
{
  "pipeline_id": "a1b2c3d4-e5f6-7890-abcd-ef1234567890",
  "start": "2024-01-01T00:00:00Z",
  "end": "2024-01-31T23:59:59Z"
}

With filters:

 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 Pipeline UUID.
pipeline_name string Pipeline name.
organization_id string Organization UUID.
start_date string Start used (ISO-8601).
end_date string End used (ISO-8601).
steps array { "step_name", "count" } per step.
pageview_counts object Present only when include_pageview_counts: true.

pageview_counts:

Attribute Type Description
visitor_count number Distinct visitors in the range.
by_source array { "source", "visitor_count" } breakdown.
source_field string Source dimension (pageview_source_field on the definition; default referrer_medium). 
 1
 2
 3
 4
 5
 6
 7
 8
 9
10
11
{
  "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 }
  ]
}

Pipeline last-state

Returns occupancy: each entity occupies at most one step — the step of its newest matching event (collector_created_at, then event_id). Uses identity_field on events (not count_field). Metrics, pageview counts, and dimension filters are not supported.

Requires supports_last_state: true on the definition (every event has identity_field). Predefined pipelines do not support last-state. After case-funnel sync, only Case status snapshot (pipeline-variant:enter-last-state) does.

Endpoint

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

Payload

Attribute Type Description
pipeline_id uuid Pipeline definition. Required.
start string Inclusive start of collector_created_at (ISO-8601). Required.
end string Inclusive end of collector_created_at (ISO-8601). Required. Must be after start.
include_inactive boolean If true, also consider events from lookback_start so entities that did not move in [start, end] still occupy a step. Default false.
lookback_start string Required when include_inactive is true; forbidden otherwise. Must be ≤ start. Window from lookback_start to end ≤ 365 days.
base_filters array Same fields as counts (geo_city, geo_country, room_ids). Default []. Applied before choosing each entity's newest event. apply_to_pageview is ignored.

A non-empty dimension filters array returns 400.

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

With inactive lookback:

1
2
3
4
5
6
7
{
  "pipeline_id": "a1b2c3d4-e5f6-7890-abcd-ef1234567890",
  "start": "2024-06-01T00:00:00Z",
  "end": "2024-06-30T23:59:59Z",
  "include_inactive": true,
  "lookback_start": "2024-01-01T00:00:00Z"
}

Response

Attribute Type Description
pipeline_id string Pipeline UUID.
pipeline_name string Pipeline name.
organization_id string Organization UUID.
start_date string Request start.
end_date string Request end.
include_inactive boolean Whether lookback was used.
lookback_start string | null Lookback bound, or null.
steps array { "step_name", "count" } — entities whose newest match is that step. 
 1
 2
 3
 4
 5
 6
 7
 8
 9
10
11
12
13
{
  "pipeline_id": "a1b2c3d4-e5f6-7890-abcd-ef1234567890",
  "pipeline_name": "Case status snapshot",
  "organization_id": "...",
  "start_date": "2024-06-01T00:00:00.000",
  "end_date": "2024-06-30T23:59:59.000",
  "include_inactive": false,
  "lookback_start": null,
  "steps": [
    { "step_name": "Open", "count": 12 },
    { "step_name": "Closed", "count": 8 }
  ]
}

Open and Closed counts are mutually exclusive for a given entity (12 + 8 = 20 entities total).

Errors

Status When
400 Missing identity_field on any event; non-empty dimension filters; invalid lookback; invalid date range.
404 Pipeline not found.
503 Analytics backend unavailable.

To list who occupies a step, use last-state detail.

Pipeline last-state detail

Same occupancy logic as /last-state, but returns the occupying identities for one step. Not the same as step-detail (counts + metrics).

Pagination coming soon

This endpoint currently returns the full details list in one response. In the near future /last-state-detail will be paginated. Plan integrations accordingly.

Endpoint

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

Payload

Same as last-state, plus:

Attribute Type Description
step_index integer Zero-based step index. Required. 
1
2
3
4
5
6
{
  "pipeline_id": "a1b2c3d4-e5f6-7890-abcd-ef1234567890",
  "start": "2024-06-01T00:00:00Z",
  "end": "2024-06-30T23:59:59Z",
  "step_index": 0
}

Response

Same window fields as last-state, plus:

Attribute Type Description
step_index number Requested step.
step_name string Step name.
count number Number of occupying entities.
details array { "identity", "datetime" } per entity (datetime = collector_created_at of the newest matching event). Empty list when none. 
 1
 2
 3
 4
 5
 6
 7
 8
 9
10
11
12
13
14
15
16
{
  "pipeline_id": "a1b2c3d4-e5f6-7890-abcd-ef1234567890",
  "pipeline_name": "Case status snapshot",
  "organization_id": "...",
  "start_date": "2024-06-01T00:00:00.000",
  "end_date": "2024-06-30T23:59:59.000",
  "include_inactive": false,
  "lookback_start": null,
  "step_index": 0,
  "step_name": "Open",
  "count": 2,
  "details": [
    { "identity": "ticket-1", "datetime": "2024-06-15T10:00:00.000" },
    { "identity": "ticket-2", "datetime": "2024-06-16T12:00:00.000" }
  ]
}

Same errors as last-state, plus 400 if step_index is out of range.

Pipeline step detail

Returns the count for one step plus any metrics defined on that step.

Endpoint

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

Payload

Attribute Type Description
pipeline_id uuid Pipeline definition. Required.
step_index integer Zero-based step index. Required.
start string Inclusive start of collector_created_at (ISO-8601). Required.
end string Inclusive end of collector_created_at (ISO-8601). Required.
base_filters array Same as counts.
filters array Same as counts. 
1
2
3
4
5
6
{
  "pipeline_id": "00000000-0000-0000-0000-000000000001",
  "step_index": 2,
  "start": "2024-01-01T00:00:00Z",
  "end": "2024-01-31T23:59:59Z"
}

Response

Attribute Type Description
pipeline_id string Pipeline UUID.
pipeline_name string Pipeline name.
step_index number Step returned.
step object Step definition (name, count_field, events, metrics).
organization_id string Organization UUID.
start_date string Start used.
end_date string End used.
data object Always includes count; plus one key per metric name.

Metric values are arrays of result rows (column names depend on group_by and aggregations). Empty array when the step has no matching events. With mapping_functions, ID values in grouped columns are translated to display names.

 1
 2
 3
 4
 5
 6
 7
 8
 9
10
11
12
13
{
  "pipeline_id": "00000000-0000-0000-0000-000000000001",
  "pipeline_name": "Impression Pipeline",
  "step_index": 2,
  "step": { "name": "Positive outcome", "count_field": "visitor_id", "events": [...], "metrics": [...] },
  "data": {
    "count": 120,
    "Users by action": [
      { "action": "openchat", "count_distinct_visitor_id": 75 },
      { "action": "leadform", "count_distinct_visitor_id": 45 }
    ]
  }
}

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