Events API

Overview

Event endpoints provide access to detailed event data, allowing you to analyze user interactions, custom events, and conversion tracking.

Event Endpoints

GET /api/websites/:websiteId/events

Returns event data with optional grouping.

Parameters:

websiteId (path): ID of the website
startDate, endDate (query, optional): Date range
limit, offset (query, optional): Pagination parameters
eventName (query, optional): Filter by event name
sessionId (query, optional): Filter by specific session ID
groupBy (query, optional): Group results by event name

Response:

{
  "events": [
    {
      "id": "event123",
      "website_id": "site456",
      "session_id": "session789",
      "hostname": "example.com",
      "browser": "Chrome",
      "os": "Windows",
      "device": "desktop",
      "country": "US",
      "url": "https://example.com/product",
      "referrer": "https://google.com",
      "page_title": "Product Page",
      "event_type": "click",
      "event_name": "add_to_cart",
      "created_at": "2023-05-15T10:30:45Z"
    }
  ],
  "pagination": {
    "total": 250,
    "limit": 100,
    "offset": 0,
    "hasMore": true
  }
}

Response (when groupBy=event):

{
  "eventCounts": [
    {
      "name": "page_view",
      "count": 8240,
      "unique_visitors": 3250
    },
    {
      "name": "click",
      "count": 5340,
      "unique_visitors": 2840
    }
  ],
  "totalEvents": 13580
}

GET /api/websites/:websiteId/event-data

Returns raw event data with flexible filtering options.

Parameters:

websiteId (path): ID of the website
startDate, endDate (query, optional): Date range
limit, offset (query, optional): Pagination parameters
eventName (query, optional): Filter by event name
sessionId (query, optional): Filter by session ID
property (query, optional): Filter by property key
propertyValue (query, optional): Filter by property value
transactionId (query, optional): Filter by transaction ID
currency (query, optional): Filter by currency
minValue, maxValue (query, optional): Filter by value range
sortBy, sortDir (query, optional): Sorting options

Response:

{
  "data": [
    {
      "id": "event123",
      "session_id": "session456",
      "name": "purchase",
      "type": "conversion",
      "timestamp": "2023-05-15T10:30:45Z",
      "url": "https://example.com/checkout/success",
      "properties": {
        "transaction_id": "TX123456",
        "currency": "USD",
        "value": 99.95,
        "items": [
          {
            "item_id": "SKU123",
            "item_name": "Product Name",
            "price": 49.95,
            "quantity": 2
          }
        ]
      }
    }
  ],
  "count": 250,
  "limit": 100,
  "offset": 0,
  "hasMore": true
}

GET /api/websites/:websiteId/event-data/fields

Returns specific fields extracted from events for easier reporting.

Parameters:

websiteId (path): ID of the website
startDate, endDate (query, optional): Date range
eventName (query, optional): Filter by event name
groupBy (query): Field to extract and group by

Response:

{
  "data": [
    {
      "session_id": "session123",
      "transaction_id": "TX123456"
    },
    {
      "session_id": "session456",
      "transaction_id": "TX789012"
    }
  ]
}

GET /api/websites/:websiteId/event-data/events

Get event data with additional event-specific filtering.

Parameters:

websiteId (path): ID of the website
startDate, endDate (query, optional): Date range
eventName (query, optional): Filter by event name
limit, offset (query, optional): Pagination parameters

Response:

{
  "events": [
    {
      "event_id": "evt123",
      "session_id": "sess456",
      "event_name": "purchase",
      "timestamp": "2023-05-15T10:30:45Z",
      "url": "https://example.com/checkout/success",
      "properties": {
        "transaction_id": "TX123456",
        "currency": "USD",
        "value": 99.95
      }
    }
  ],
  "count": 250,
  "hasMore": true
}

GET /api/websites/:websiteId/event-data/values

Get unique values for event properties.

Parameters:

websiteId (path): ID of the website
startDate, endDate (query, optional): Date range
eventName (query, optional): Filter by event name
property (query): Property to get values for

Response:

{
  "values": [
    "USD",
    "EUR",
    "GBP"
  ]
}

GET /api/websites/:websiteId/event-data/stats

Get statistical information about event data.

Parameters:

websiteId (path): ID of the website
startDate, endDate (query, optional): Date range
eventName (query, optional): Filter by event name

Response:

{
  "total_events": 15420,
  "unique_sessions": 8930,
  "event_types": [
    {
      "name": "page_view",
      "count": 8240,
      "percentage": 53.4
    },
    {
      "name": "click",
      "count": 5340,
      "percentage": 34.6
    }
  ],
  "date_range": {
    "start": "2023-05-01T00:00:00Z",
    "end": "2023-05-15T23:59:59Z"
  }
}

Usage Examples

Get All Events for a Time Period

GET /api/websites/abc123/events?startDate=2023-05-01&endDate=2023-05-15&limit=100

Get Events by Type

GET /api/websites/abc123/events?eventName=purchase&limit=50

Get Event Counts Grouped by Event Name

GET /api/websites/abc123/events?groupBy=event

Get E-commerce Purchase Data

GET /api/websites/abc123/event-data?eventName=purchase&sortBy=created_at&sortDir=desc

Extract Transaction IDs from Purchase Events

GET /api/websites/abc123/event-data/fields?eventName=purchase&groupBy=transaction_id

Get Revenue Data with Value Filtering

GET /api/websites/abc123/event-data?eventName=purchase&minValue=50&maxValue=500&currency=USD

Get Unique Currency Values

GET /api/websites/abc123/event-data/values?eventName=purchase&property=currency

Event Property Filtering

You can filter events by their custom properties:

Filter by Simple Property

GET /api/websites/abc123/event-data?property=button_text&propertyValue=Sign%20Up

Filter by Nested Property

Use dot notation for nested properties:

GET /api/websites/abc123/event-data/fields?groupBy=items_item_0_item_id

Filter by Value Range

For numeric properties:

GET /api/websites/abc123/event-data?eventName=purchase&minValue=100&maxValue=1000

Sorting Options

Sort events by various fields:

created_at: Event timestamp (default)
event_name: Event name alphabetically
value: Numeric value (for e-commerce events)
session_id: Session identifier

Sort Direction:

asc: Ascending order
desc: Descending order (default)

Common Event Analysis Patterns

Conversion Funnel Analysis

# Step 1: Get page views
GET /api/websites/abc123/events?eventName=page_view&url=/product

# Step 2: Get add to cart events
GET /api/websites/abc123/events?eventName=add_to_cart

# Step 3: Get purchase events
GET /api/websites/abc123/events?eventName=purchase

User Journey Analysis

# Get all events for a specific session
GET /api/websites/abc123/events?sessionId=session123&sortBy=created_at&sortDir=asc

Revenue Analysis

# Get total revenue by extracting values
GET /api/websites/abc123/event-data/fields?eventName=purchase&groupBy=value

# Get revenue by product
GET /api/websites/abc123/event-data/fields?eventName=purchase&groupBy=items_item_0_item_name

Getting Started

Setup

Analytics

Server-side Hosts

Connections

ETL/Data Governance

FAQ

Changelog

Overview

Event Endpoints

Usage Examples

Get All Events for a Time Period

Get Events by Type

Get Event Counts Grouped by Event Name

Get E-commerce Purchase Data

Extract Transaction IDs from Purchase Events

Get Revenue Data with Value Filtering

Get Unique Currency Values

Event Property Filtering

Filter by Simple Property

Filter by Nested Property

Filter by Value Range

Sorting Options

Common Event Analysis Patterns

Conversion Funnel Analysis

User Journey Analysis

Revenue Analysis

Getting Started

Setup

Analytics

Server-side Hosts

Connections

ETL/Data Governance

FAQ

Changelog

​Overview

​Event Endpoints

​Usage Examples

​Get All Events for a Time Period

​Get Events by Type

​Get Event Counts Grouped by Event Name

​Get E-commerce Purchase Data

​Extract Transaction IDs from Purchase Events

​Get Revenue Data with Value Filtering

​Get Unique Currency Values

​Event Property Filtering

​Filter by Simple Property

​Filter by Nested Property

​Filter by Value Range

​Sorting Options

​Common Event Analysis Patterns

​Conversion Funnel Analysis

​User Journey Analysis

​Revenue Analysis

Overview

Event Endpoints

Usage Examples

Get All Events for a Time Period

Get Events by Type

Get Event Counts Grouped by Event Name

Get E-commerce Purchase Data

Extract Transaction IDs from Purchase Events

Get Revenue Data with Value Filtering

Get Unique Currency Values

Event Property Filtering

Filter by Simple Property

Filter by Nested Property

Filter by Value Range

Sorting Options

Common Event Analysis Patterns

Conversion Funnel Analysis

User Journey Analysis

Revenue Analysis