Generic events¶

List raw generic-event rows.

To see which vendor / category / action combinations exist first, use the event type catalog.

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. Page size is 250. Walk adjacent windows and paginate each one for a longer range. 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.

List events¶

Returns matching generic-event rows. Internal categories are not hidden — if your filter matches them, they appear.

Uses the same match fields as a pipeline step (vendor, category, action, label, room_ids, properties). Multiple filter objects are OR-ed; fields inside one object are AND-ed. Not a pipeline run: no pipeline_id. identity_field is not a list filter — it is ignored if sent.

$name value set references are allowed on vendor, category, action, label, and room_ids. Each filter object must also include at least one concrete field value — a filter that is only $ references is rejected. A missing value set leaves that field unconstrained. properties has no value-set support.

Endpoint

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

Payload (first page)

Attribute	Type	Description
`start`	datetime	Inclusive start of `collector_created_at`. Required.
`end`	datetime	Inclusive end of `collector_created_at`. Required. Must be after `start`. Max window: 2 days.
`events`	array	At least one event filter. Match any filter (OR); fields within a filter are AND-ed.
`order`	string	`"desc"` (default) or `"asc"`. Sort is `collector_created_at`, then `event_id`.

Payload (next page)

Attribute	Type	Description
`cursor`	string	`next_cursor` from the previous response. When set, every other body field is ignored (window, `events`, and `order` included).

Page size is 250. Forward-only pagination until next_cursor is null.

Event filters¶

Each object may include any of: vendor, category, action, label, room_ids, properties. At least one must be a concrete value (not only a $name reference). Omitted fields are unconstrained.

Field	Type	Semantics
`vendor`, `category`, `action`, `label`	string, list of strings, or `$name`	Exact match, or match any value in the list.
`room_ids`	string, list, or `$name`	`hasAny` against room IDs parsed from `properties` (`room_id=…`). Not a stored column.
`properties`	list of `"key=value"` strings	All listed entries must be present (`hasAll`). No value-set references.

identity_field is ignored if sent. A list value is the same as OR on that field; use several objects when field combinations differ.

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

Response

Attribute	Type	Description
`results`	array	Matching event objects. Columns: Result object.
`next_cursor`	string \| null	Token for the next page, or `null` when finished.

Errors: 400 for invalid window/filters/cursor; 401/403 for auth; 503 when the analytics backend is unavailable.

Result object¶

Every matching row includes these fields.

Field	Type	Description
`collector_created_at`	datetime	Event time. Used for windows, sort, and pagination. Functionally the same as `timestamp` (possibly a few ms apart).
`timestamp`	datetime	Event time. Functionally the same as `collector_created_at`. Both exist for legacy reasons; a later API will use `timestamp` only.
`source`	string	`trusted` or `untrusted`.
`event_version`	integer	Event schema version.
`event_id`	uuid	Unique event id.
`organization_id`	uuid	Owner organization.
`organization_name`	string	Organization name.
`vendor`	string	Event vendor.
`category`	string	Event category.
`action`	string	Event action.
`label`	string	Event label.
`properties`	array of strings	Extra `key=value` entries.
`dim1`	string \| null	Custom dimension.
`dim2`	string \| null	Custom dimension.
`dim3`	string \| null	Custom dimension.
`dim4`	string \| null	Custom dimension.
`dim5`	string \| null	Custom dimension.
`visitor_id`	string \| null	Visitor id.
`session_id`	uuid \| null	Visitor session id.
`user_id`	uuid \| null	User id.
`partner_organization_ids`	array of uuid	Partner organization ids.
`browser_name`	string \| null	Visitor browser name.
`browser_version`	string \| null	Visitor browser version.
`device_screen_height`	integer \| null	Screen height.
`device_screen_width`	integer \| null	Screen width.
`device_type`	string \| null	Device type.
`geo_city`	string \| null	Visitor city.
`geo_country`	string \| null	Visitor country.
`ip_organization`	string \| null	ISP or company from IP.
`os_name`	string \| null	Operating system.
`os_version`	string \| null	Operating system version.
`value`	number	Numeric value (meaning depends on the event).

How dim1–dim5, label, and properties are used on case-management events: Case management events.