Overview The Sessions endpoint provides comprehensive session analytics data including visitor journeys, session durations, page views, and detailed session metadata. Perfect for understanding user behavior patterns, analyzing conversion paths, and building detailed user journey reports.
Track individual user sessions with full context including device information, geographic data, UTM parameters, and custom session properties.
Endpoint GET https://app.usehardal.com/api/websites/{signalId}/sessions Authentication Include your API key in the Authorization header:
Authorization: Bearer YOUR_API_KEY Parameters Parameter Type Required Default Description signalIdstring Yes - Your website signal ID (URL path) limitinteger No 1000 Number of sessions to return (pagination) offsetinteger No 0 Number of sessions to skip (pagination) timeframestring No custom Time period: today, yesterday, last7days, last30days, custom startDatestring No - Start date for timeframe (ISO format) endDatestring No - End date for timeframe (ISO format) targetSignalIdstring No signalId Target signal ID for analytics data timezonestring No Europe/Istanbul Timezone for date calculations (e.g., Asia/Istanbul) isHybridboolean No false Whether this is a hybrid/self-hosted signal
Quick Start Environment Setup Finding your signal ID: Go to your Hardal dashboard → select your project → view the signal ID in the URL or settings.
Finding your API key: Go to your Hardal dashboard → select your signal → Settings → Security → API Keys.
Start with a simple request to get recent sessions:
Get the latest sessions with default pagination (1000 sessions).
curl -X GET \ "https://app.usehardal.com/api/websites/${ SIGNAL_ID }/sessions" \ -H "Authorization: Bearer YOUR_API_KEY" \ -H "Content-Type: application/json" Response:
{ "sessions" : [ { "id" : "sess_abc123456" , "visitorId" : "visitor_789" , "startedAt" : "2024-01-15T10:30:00+03:00" , "duration" : "180s" , "pageViews" : 5 , "events" : 12 , "pages" : [ "/" , "/products" , "/products/item-1" , "/cart" , "/checkout" ], "browser" : "Chrome" , "os" : "Windows" , "device" : "Desktop" , "country" : "Turkey" , "fields" : { "utm_source" : "google" , "utm_medium" : "cpc" , "utm_campaign" : "summer_sale" , "user_id" : "user_456" } } ], "pagination" : { "total" : 1250 , "limit" : 1000 , "offset" : 0 , "currentPage" : 1 , "totalPages" : 2 , "hasMore" : true } } Usage Examples
Get all sessions from today with small pagination for real-time monitoring.
curl -X GET \ "https://app.usehardal.com/api/websites/${ SIGNAL_ID }/sessions?limit=10&offset=0&timeframe=today&targetSignalId=${ SIGNAL_ID }&timezone=Asia%2FIstanbul&isHybrid=false" \ -H "Authorization: Bearer YOUR_API_KEY" \ -H "Content-Type: application/json" Response:
{ "sessions" : [ { "id" : "sess_abc123456" , "visitorId" : "visitor_789" , "startedAt" : "2025-07-03T14:30:00+03:00" , "duration" : "240s" , "pageViews" : 3 , "events" : 8 , "pages" : [ "/" , "/products" , "/contact" ], "browser" : "Chrome" , "os" : "Windows" , "device" : "Desktop" , "country" : "Turkey" , "fields" : { "utm_source" : "google" , "utm_medium" : "organic" } } ], "pagination" : { "total" : 45 , "limit" : 10 , "offset" : 0 , "currentPage" : 1 , "totalPages" : 5 , "hasMore" : true } } Use Case: Real-time session monitoring, live dashboard updates
Analyze yesterday’s complete session data for daily reporting.
curl -X GET \ "https://app.usehardal.com/api/websites/${ SIGNAL_ID }/sessions?limit=50&offset=0&timeframe=yesterday&targetSignalId=${ SIGNAL_ID }&timezone=Asia%2FIstanbul&isHybrid=false" \ -H "Authorization: Bearer YOUR_API_KEY" \ -H "Content-Type: application/json" Response:
{ "sessions" : [ { "id" : "sess_def789012" , "visitorId" : "visitor_123" , "startedAt" : "2025-07-02T10:25:00+03:00" , "duration" : "450s" , "pageViews" : 7 , "events" : 15 , "pages" : [ "/" , "/products" , "/products/item-1" , "/products/item-2" , "/cart" , "/checkout" , "/order-success" ], "browser" : "Safari" , "os" : "macOS" , "device" : "Desktop" , "country" : "United States" , "fields" : { "utm_source" : "twitter" , "utm_medium" : "social" , "utm_campaign" : "launch_promo" , "user_id" : "user_789" } } ], "pagination" : { "total" : 187 , "limit" : 50 , "offset" : 0 , "currentPage" : 1 , "totalPages" : 4 , "hasMore" : true } } Use Case: Daily performance analysis, conversion funnel review
Get weekly session data for trend analysis and user behavior patterns.
curl -X GET \ "https://app.usehardal.com/api/websites/${ SIGNAL_ID }/sessions?limit=100&offset=0&timeframe=last7days&targetSignalId=${ SIGNAL_ID }&timezone=Asia%2FIstanbul&isHybrid=false" \ -H "Authorization: Bearer YOUR_API_KEY" \ -H "Content-Type: application/json" Response:
{ "sessions" : [ { "id" : "sess_ghi345678" , "visitorId" : "visitor_456" , "startedAt" : "2025-06-28T16:20:00+03:00" , "duration" : "95s" , "pageViews" : 2 , "events" : 4 , "pages" : [ "/" , "/about" ], "browser" : "Firefox" , "os" : "Linux" , "device" : "Desktop" , "country" : "Germany" , "fields" : { "utm_source" : "newsletter" , "utm_medium" : "email" , "utm_campaign" : "weekly_update" } } ], "pagination" : { "total" : 832 , "limit" : 100 , "offset" : 0 , "currentPage" : 1 , "totalPages" : 9 , "hasMore" : true } } Use Case: Weekly reporting, user journey analysis, campaign performance
Get monthly session data for comprehensive analytics and trend identification.
curl -X GET \ "https://app.usehardal.com/api/websites/${ SIGNAL_ID }/sessions?limit=200&offset=0&timeframe=last30days&targetSignalId=${ SIGNAL_ID }&timezone=Asia%2FIstanbul&isHybrid=false" \ -H "Authorization: Bearer YOUR_API_KEY" \ -H "Content-Type: application/json" Response:
{ "sessions" : [ { "id" : "sess_jkl901234" , "visitorId" : "visitor_890" , "startedAt" : "2025-06-15T11:45:00+03:00" , "duration" : "320s" , "pageViews" : 6 , "events" : 18 , "pages" : [ "/" , "/pricing" , "/features" , "/signup" , "/dashboard" , "/welcome" ], "browser" : "Chrome" , "os" : "Android" , "device" : "Mobile" , "country" : "India" , "fields" : { "utm_source" : "facebook" , "utm_medium" : "cpc" , "utm_campaign" : "mobile_app_install" , "user_id" : "user_101112" } } ], "pagination" : { "total" : 3456 , "limit" : 200 , "offset" : 0 , "currentPage" : 1 , "totalPages" : 18 , "hasMore" : true } } Use Case: Monthly reports, long-term trend analysis, cohort analysis
Custom Date Range Sessions
Query sessions for a specific date range with detailed timezone handling.
curl -X GET \ "https://app.usehardal.com/api/websites/${ SIGNAL_ID }/sessions?limit=25&offset=0&startDate=2025-06-27T00%3A00%3A00&endDate=2025-06-28T00%3A00%3A00&targetSignalId=${ SIGNAL_ID }&timezone=Asia%2FIstanbul&isHybrid=false" \ -H "Authorization: Bearer YOUR_API_KEY" \ -H "Content-Type: application/json" Response:
{ "sessions" : [ { "id" : "sess_mno567890" , "visitorId" : "visitor_234" , "startedAt" : "2025-06-27T14:30:00+03:00" , "duration" : "1200s" , "pageViews" : 12 , "events" : 35 , "pages" : [ "/" , "/blog" , "/blog/post-1" , "/blog/post-2" , "/about" , "/contact" , "/services" , "/portfolio" , "/pricing" , "/signup" , "/dashboard" , "/profile" ], "browser" : "Edge" , "os" : "Windows" , "device" : "Desktop" , "country" : "Canada" , "fields" : { "utm_source" : "bing" , "utm_medium" : "cpc" , "utm_campaign" : "brand_awareness" , "referrer" : "https://www.bing.com/search" } } ], "pagination" : { "total" : 89 , "limit" : 25 , "offset" : 0 , "currentPage" : 1 , "totalPages" : 4 , "hasMore" : true } } Use Case: Event-specific analysis, campaign performance measurement, A/B testing
Navigate through large datasets using pagination.
# Get second page of sessions curl -X GET \ "https://app.usehardal.com/api/websites/${ SIGNAL_ID }/sessions?limit=50&offset=50&timeframe=last7days&targetSignalId=${ SIGNAL_ID }&timezone=Asia%2FIstanbul&isHybrid=false" \ -H "Authorization: Bearer YOUR_API_KEY" \ -H "Content-Type: application/json" Response:
{ "sessions" : [ { "id" : "sess_pqr345678" , "visitorId" : "visitor_567" , "startedAt" : "2025-06-26T09:15:00+03:00" , "duration" : "67s" , "pageViews" : 1 , "events" : 2 , "pages" : [ "/landing-page" ], "browser" : "Chrome" , "os" : "iOS" , "device" : "Mobile" , "country" : "United Kingdom" , "fields" : { "utm_source" : "instagram" , "utm_medium" : "social" , "utm_campaign" : "story_ad" } } ], "pagination" : { "total" : 832 , "limit" : 50 , "offset" : 50 , "currentPage" : 2 , "totalPages" : 17 , "hasMore" : true } } Use Case: Large dataset processing, bulk data export, detailed analysis
Response Fields Session Object
id: Unique session identifiervisitorId: Unique visitor identifier (tracks user across sessions)startedAt: Session start timestamp (formatted in specified timezone)duration: Session duration in seconds (e.g., “180s” for 3 minutes)pageViews: Number of page views in this sessionevents: Total number of events triggered in this sessionpages: Array of unique page URLs visited during the sessionbrowser: Browser name (Chrome, Safari, Firefox, Edge, etc.)os: Operating system (Windows, macOS, Linux, iOS, Android)device: Device type (Desktop, Mobile, Tablet)country: Country name based on IP geolocationfields: Custom session properties and UTM parameters
Session Fields Object Contains custom session properties that may include:
utm_source: Traffic source (e.g., “google”, “twitter”, “newsletter”)utm_medium: Traffic medium (e.g., “cpc”, “social”, “email”, “organic”)utm_campaign: Campaign name (e.g., “summer_sale”, “product_launch”)user_id: Authenticated user identifier (if user is logged in)referrer: Original referrer URLcustom_field_1, custom_field_2: Any custom tracking parameters you’ve implemented
total: Total number of sessions available for the querylimit: Number of sessions requested per pageoffset: Number of sessions skipped (for pagination)currentPage: Current page number (1-based indexing)totalPages: Total number of pages availablehasMore: Boolean indicating if more sessions are available
The sessions endpoint supports efficient pagination:
# Navigate through pages # Page 1: First 100 sessions curl -X GET \ "https://app.usehardal.com/api/websites/${ SIGNAL_ID }/sessions?limit=100&offset=0" \ -H "Authorization: Bearer YOUR_API_KEY" # Page 2: Next 100 sessions curl -X GET \ "https://app.usehardal.com/api/websites/${ SIGNAL_ID }/sessions?limit=100&offset=100" \ -H "Authorization: Bearer YOUR_API_KEY" # Page 3: Next 100 sessions curl -X GET \ "https://app.usehardal.com/api/websites/${ SIGNAL_ID }/sessions?limit=100&offset=200" \ -H "Authorization: Bearer YOUR_API_KEY" Performance Tips:
Use reasonable page sizes (10-200 sessions per request)
Default limit is 1000 sessions if not specified
Use hasMore field to determine if more pages exist
Sessions are ordered by startedAt timestamp (newest first)
Usage Notes
Session Duration : Calculated from first to last event in the sessionPage Array : Contains unique URLs visited during the session (no duplicates)Custom Fields : Session fields contain UTM parameters and custom properties when availableTimezone Handling : All timestamps are formatted according to the specified timezoneDefault Limits : Maximum 1000 sessions per request if not specifiedOrdering : Sessions are ordered by startedAt timestamp in descending order (newest first)Minimum Duration : Sessions with zero duration are given a minimum duration of 1 secondPage Numbering : Pagination uses 1-based page numbering in the response 
