Skip to content

Listing generic events

Fetch individual generic-event rows — for debugging, exports, or inspecting case activity.

Chat messages are a different dataset: Listing chat message events.
To see which vendor / category / action combinations exist first, use the event type catalog.

Base URL: https://api.giosg.com/api/objectives/v1/orgs/<organization_id>

Authentication

For server-to-server calls, authenticate with a user API token: Authorization: Token <api token>. OAuth2 access tokens use Authorization: Bearer <access token> instead. How to obtain and use each: Get API token. The URL organization_id must match the authenticated organization.

Two-day window

Each request covers at most 2 days. Results come in pages of 250. To cover a longer range, walk adjacent windows and paginate each one. If cursor is sent, every other body field is ignored. Windows use collector_created_at; that field and timestamp are functionally the same (they may differ by milliseconds). Both exist for legacy reasons — a later API will use timestamp only.

Basic request

 1
 2
 3
 4
 5
 6
 7
 8
 9
10
11
12
POST /events
Authorization: Token <api token>
Content-Type: application/json

{
  "start": "2024-01-01T00:00:00Z",
  "end": "2024-01-02T23:59:59Z",
  "events": [
    { "category": "case_management" }
  ],
  "order": "desc"
}

Filters use vendor, category, action, label, room_ids, and properties. Each of vendor, category, action, label, and room_ids can be a string, a list of strings, or a $name value-set reference. Multiple objects are OR-ed. Include at least one concrete value (not only a $value-set reference). room_ids is not a stored column — it is parsed from properties entries of the form room_id=…. identity_field is ignored if sent.

The same match fields are used on pipeline steps (without identity_field), so a filter you test here can later become a step.

Value sets

vendor, category, action, label, and room_ids can reference a pipeline value set as $name. The list is resolved for your organization at query time. Pair it with at least one concrete field — a filter that is only $ references is rejected (a missing or empty set would otherwise match everything).

1
2
3
4
5
6
7
{
  "start": "2024-01-01T00:00:00Z",
  "end": "2024-01-02T23:59:59Z",
  "events": [
    { "category": "widget", "action": "click", "label": "$interaction-ids" }
  ]
}

properties does not support value-set references. Chat message events do not use value sets.

Case-management examples

All four actions share category: case_management. What they mean and which fields they carry: Case management events.

Every case-management row in the window:

1
2
3
4
5
6
7
{
  "start": "2024-01-01T00:00:00Z",
  "end": "2024-01-02T23:59:59Z",
  "events": [
    { "category": "case_management" }
  ]
}

Entries into one funnel stage (step_started, label = stage id):

 1
 2
 3
 4
 5
 6
 7
 8
 9
10
11
{
  "start": "2024-01-01T00:00:00Z",
  "end": "2024-01-02T23:59:59Z",
  "events": [
    {
      "category": "case_management",
      "action": "step_started",
      "label": "<case_funnel_stage_id>"
    }
  ]
}

Pagination

If next_cursor is set, request the next page with only that cursor. Every other body field is ignored (window, events, and order included):

1
{ "cursor": "<next_cursor>" }

Repeat until next_cursor is null. To cover more than two days, use adjacent windows and paginate each one.

Full request/response tables: Generic events reference. Columns on each row: Result object.