Skip to content

Quickstart: using predefined pipelines

The fastest way to get pipeline counts is to use one of the predefined pipelines — global, read-only metrics available to all organizations. No pipeline definition to create; just fetch counts against a fixed ID.

Prerequisites: a valid API token and your organization_id.
Base URL: https://api.giosg.com/api/objectives/v1/orgs/<organization_id>/pipeline

Want to build your own pipeline instead? See Building a custom pipeline.
For a full endpoint reference, see the Pipeline API reference.

Step 1 — List the available predefined pipelines

1
2
GET https://api.giosg.com/api/objectives/v1/orgs/<organization_id>/pipeline/predefined-definitions
Authorization: Bearer <token>

The response is a list of predefined pipelines. There are currently two:

  • Impression Pipeline (00000000-0000-0000-0000-000000000001) — impressions → engaged → positive outcome → goals. Uses your interaction-ids and goal-ids value sets.
  • Shopping Cart Pipeline (00000000-0000-0000-0000-000000000002) — cart created → cart purchased → cart purchased with real chat. No value sets needed.

Example response (trimmed):

 1
 2
 3
 4
 5
 6
 7
 8
 9
10
11
12
13
14
15
16
[
  {
    "id": "00000000-0000-0000-0000-000000000001",
    "name": "Impression Pipeline",
    "is_predefined": true,
    "steps": [ ... ],
    "dimensions": [ ... ]
  },
  {
    "id": "00000000-0000-0000-0000-000000000002",
    "name": "Shopping Cart Pipeline",
    "is_predefined": true,
    "steps": [ ... ],
    "dimensions": []
  }
]

Copy the id of the pipeline you want.

Step 2 — Get counts

Use the standard counts endpoint with the predefined pipeline's ID:

1
2
3
4
5
6
7
8
9
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"
}

Response:

 1
 2
 3
 4
 5
 6
 7
 8
 9
10
11
12
13
{
  "pipeline_id": "00000000-0000-0000-0000-000000000001",
  "pipeline_name": "Impression Pipeline",
  "organization_id": "...",
  "start_date": "2024-01-01T00:00:00.000",
  "end_date": "2024-01-31T23:59:59.000",
  "steps": [
    { "step_name": "Impressions",          "count": 123 },
    { "step_name": "Engaged with giosg",   "count": 45  },
    { "step_name": "Positive outcome",     "count": 12  },
    { "step_name": "Goals reached",        "count": 3   }
  ]
}

Impression Pipeline and value sets

The Impression Pipeline filters its steps by $interaction-ids and $goal-ids. If a value set doesn't exist for your organization, that filter condition is omitted entirely and the step counts all matching events. See Building a custom pipeline — value sets for how to create them.

The Shopping Cart Pipeline needs no value sets — it uses literal event filters.

Step 3 (optional) — Include pageview counts

Add "include_pageview_counts": true to get total visitor counts from the pageview table alongside your step counts, broken down by referral source:

1
2
3
4
5
6
{
  "pipeline_id": "00000000-0000-0000-0000-000000000001",
  "start": "2024-01-01T00:00:00Z",
  "end": "2024-01-31T23:59:59Z",
  "include_pageview_counts": true
}

The response gains a pageview_counts object:

 1
 2
 3
 4
 5
 6
 7
 8
 9
10
11
{
  "steps": [ ... ],
  "pageview_counts": {
    "visitor_count": 5000,
    "by_source": [
      { "source": "organic", "visitor_count": 2100 },
      { "source": "direct",  "visitor_count": 1800 }
    ],
    "source_field": "referrer_medium"
  }
}

source_field is taken from the pipeline definition's pageview_source_field (here referrer_medium).

Next steps