Sessions API

Overview

Session endpoints provide access to user session data, allowing you to analyze user behavior, session duration, and user journeys across your website.

Session Endpoints

GET /api/websites/:websiteId/sessions

Returns a list of sessions with pagination.

Parameters:

websiteId (path): ID of the website
startDate, endDate (query, optional): Date range
limit, offset (query, optional): Pagination parameters
filter (query, optional): Filter in format ‘key:value’ (e.g., ‘browser:Chrome’)

Response:

{
  "sessions": [
    {
      "id": "session123",
      "visitorId": "visitor456",
      "startedAt": "2023-05-15T10:00:00Z",
      "duration": "350s",
      "pageViews": 5,
      "events": 12,
      "pages": ["/home", "/products", "/product/123"],
      "browser": "Chrome",
      "os": "Windows",
      "device": "desktop",
      "country": "US",
      "fields": {
        "utm_source": "google",
        "utm_medium": "cpc"
      }
    }
  ],
  "pagination": {
    "total": 250,
    "limit": 100,
    "offset": 0,
    "hasMore": true
  }
}

GET /api/websites/:websiteId/sessions/stats

Get session statistics and aggregated data.

Parameters:

websiteId (path): ID of the website
startDate, endDate (query, optional): Date range
groupBy (query, optional): Group by ‘browser’, ‘os’, ‘device’, ‘country’

Response:

{
  "total_sessions": 15420,
  "unique_visitors": 8930,
  "avg_session_duration": 245.6,
  "avg_pages_per_session": 3.2,
  "bounce_rate": 42.5,
  "breakdown": [
    {
      "name": "Chrome",
      "sessions": 8240,
      "percentage": 53.4
    },
    {
      "name": "Safari",
      "sessions": 3850,
      "percentage": 25.0
    }
  ]
}

GET /api/websites/:websiteId/sessions/:sessionId

Get detailed information about a specific session.

Parameters:

websiteId (path): ID of the website
sessionId (path): ID of the session

Response:

{
  "session": {
    "session_id": "sess123",
    "visitor_id": "visitor456",
    "created_at": "2023-05-15T10:00:00Z",
    "duration": 300,
    "pageviews": 5,
    "events": 12,
    "browser": "Chrome",
    "os": "Windows",
    "device": "Desktop",
    "country": "United States",
    "referrer": "https://google.com",
    "landing_page": "/home",
    "exit_page": "/contact"
  },
  "events": [
    {
      "event_name": "page_view",
      "url": "/home",
      "timestamp": "2023-05-15T10:00:00Z",
      "page_title": "Home Page"
    },
    {
      "event_name": "click",
      "url": "/home",
      "timestamp": "2023-05-15T10:01:30Z",
      "properties": {
        "button_text": "Learn More"
      }
    }
  ]
}

GET /api/websites/:websiteId/sessions/:sessionId/activity

Get activity timeline for a specific session.

Parameters:

websiteId (path): ID of the website
sessionId (path): ID of the session

Response:

{
  "session_id": "sess123",
  "timeline": [
    {
      "timestamp": "2023-05-15T10:00:00Z",
      "type": "page_view",
      "url": "/home",
      "title": "Home Page",
      "duration_on_page": 90
    },
    {
      "timestamp": "2023-05-15T10:01:30Z",
      "type": "click",
      "url": "/home",
      "element": "Learn More Button"
    },
    {
      "timestamp": "2023-05-15T10:02:15Z",
      "type": "page_view",
      "url": "/products",
      "title": "Products",
      "duration_on_page": 120
    }
  ],
  "summary": {
    "total_duration": 300,
    "pages_visited": 3,
    "interactions": 8
  }
}

GET /api/websites/:websiteId/sessions/:sessionId/properties

Get custom properties for a specific session.

Parameters:

websiteId (path): ID of the website
sessionId (path): ID of the session

Response:

[
  {
    "websiteId": "web123",
    "sessionId": "sess456",
    "dataKey": "email",
    "dataType": 1,
    "stringValue": "user@example.com",
    "createdAt": "2023-05-15T10:00:00Z"
  },
  {
    "websiteId": "web123",
    "sessionId": "sess456",
    "dataKey": "plan",
    "dataType": 1,
    "stringValue": "premium",
    "createdAt": "2023-05-15T10:00:00Z"
  }
]

GET /api/websites/:websiteId/session-data/properties

Get session properties across multiple sessions.

Parameters:

websiteId (path): ID of the website
startDate, endDate (query, optional): Date range
property (query, optional): Filter by property key
value (query, optional): Filter by property value
limit, offset (query, optional): Pagination parameters

Response:

{
  "data": [
    {
      "session_id": "sess123",
      "property_key": "email",
      "property_value": "user@example.com",
      "created_at": "2023-05-15T10:00:00Z"
    },
    {
      "session_id": "sess456",
      "property_key": "plan",
      "property_value": "premium",
      "created_at": "2023-05-15T10:05:00Z"
    }
  ],
  "pagination": {
    "total": 150,
    "limit": 100,
    "offset": 0,
    "hasMore": true
  }
}

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

Get unique values for session properties.

Parameters:

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

Response:

{
  "property": "plan",
  "values": [
    "free",
    "premium",
    "enterprise"
  ],
  "count": 3
}

Usage Examples

Get Recent Sessions

GET /api/websites/abc123/sessions?limit=50&offset=0

Get Sessions from Specific Browser

GET /api/websites/abc123/sessions?filter=browser:Chrome&limit=100

Get Session Statistics by Device

GET /api/websites/abc123/sessions/stats?groupBy=device

Get Detailed Session Information

GET /api/websites/abc123/sessions/sess123456

Get Session Activity Timeline

GET /api/websites/abc123/sessions/sess123456/activity

Get Sessions with Custom Properties

GET /api/websites/abc123/session-data/properties?property=email

Get Unique Plan Values

GET /api/websites/abc123/session-data/values?property=plan

Session Filtering

You can filter sessions using various criteria:

Filter by Technology

# Filter by browser
GET /api/websites/abc123/sessions?filter=browser:Chrome

# Filter by operating system
GET /api/websites/abc123/sessions?filter=os:Windows

# Filter by device type
GET /api/websites/abc123/sessions?filter=device:desktop

Filter by Geography

# Filter by country
GET /api/websites/abc123/sessions?filter=country:US

Filter by Time Range

# Get sessions from last 7 days
GET /api/websites/abc123/sessions?startDate=2023-05-08&endDate=2023-05-15

Session Metrics

Key Session Metrics

Duration: Total time spent in the session
Page Views: Number of pages viewed
Events: Total number of events triggered
Bounce Rate: Percentage of single-page sessions
Pages per Session: Average pages viewed per session

Session Quality Indicators

Engagement Score: Based on duration and interactions
Conversion: Whether the session resulted in a conversion event
Return Visitor: Whether this is a returning visitor

Common Session Analysis Patterns

User Journey Analysis

# Get session details to understand user path
GET /api/websites/abc123/sessions/sess123/activity

Cohort Analysis

# Get sessions by date range for cohort analysis
GET /api/websites/abc123/sessions?startDate=2023-05-01&endDate=2023-05-07

User Segmentation

# Get sessions with specific properties for segmentation
GET /api/websites/abc123/session-data/properties?property=user_type&value=premium

Performance Analysis

# Get session statistics to analyze performance
GET /api/websites/abc123/sessions/stats?groupBy=browser

Getting Started

Setup

Analytics

Server-side Hosts

Connections

ETL/Data Governance

FAQ

Changelog

Overview

Session Endpoints

Usage Examples

Get Recent Sessions

Get Sessions from Specific Browser

Get Session Statistics by Device

Get Detailed Session Information

Get Session Activity Timeline

Get Sessions with Custom Properties

Get Unique Plan Values

Session Filtering

Filter by Technology

Filter by Geography

Filter by Time Range

Session Metrics

Key Session Metrics

Session Quality Indicators

Common Session Analysis Patterns

User Journey Analysis

Cohort Analysis

User Segmentation

Performance Analysis

Getting Started

Setup

Analytics

Server-side Hosts

Connections

ETL/Data Governance

FAQ

Changelog

​Overview

​Session Endpoints

​Usage Examples

​Get Recent Sessions

​Get Sessions from Specific Browser

​Get Session Statistics by Device

​Get Detailed Session Information

​Get Session Activity Timeline

​Get Sessions with Custom Properties

​Get Unique Plan Values

​Session Filtering

​Filter by Technology

​Filter by Geography

​Filter by Time Range

​Session Metrics

​Key Session Metrics

​Session Quality Indicators

​Common Session Analysis Patterns

​User Journey Analysis

​Cohort Analysis

​User Segmentation

​Performance Analysis

Overview

Session Endpoints

Usage Examples

Get Recent Sessions

Get Sessions from Specific Browser

Get Session Statistics by Device

Get Detailed Session Information

Get Session Activity Timeline

Get Sessions with Custom Properties

Get Unique Plan Values

Session Filtering

Filter by Technology

Filter by Geography

Filter by Time Range

Session Metrics

Key Session Metrics

Session Quality Indicators

Common Session Analysis Patterns

User Journey Analysis

Cohort Analysis

User Segmentation

Performance Analysis