Active Users API

Overview

The Active Users endpoint provides real-time visibility into who’s currently browsing your website. Track active visitors, see what pages they’re viewing, and monitor live traffic patterns with customizable time windows.

Perfect for real-time dashboards, live visitor widgets, and monitoring traffic spikes as they happen.

Endpoint

GET https://app.usehardal.com/api/websites/{signalId}/active

Authentication

Include your API key in the Authorization header:

Authorization: Bearer YOUR_API_KEY

Parameters

Parameter	Type	Required	Default	Description
`signalId`	string	Yes	-	Your website signal ID (URL path)
`minutes`	integer	No	5	Time window in minutes to look back for active visitors
`targetSignalId`	string	No	signalId	Target signal ID for analytics data
`isHybrid`	boolean	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.

Finding your API key: Go to your Hardal dashboard → select your signal → Settings → Security.

Start with a simple request:

Basic Request

Get active visitors from last 5 minutes.

curl -X GET \
  "https://app.usehardal.com/api/websites/${SIGNAL_ID}/active" \
  -H "Authorization: Bearer ${API_KEY}"

Response:

{
  "count": 5,
  "visitors": [
    {
      "id": "session_abc123",
      "sessionId": "session_abc123",
      "page": "/dashboard",
      "title": "Dashboard - My App",
      "referrer": "https://google.com",
      "browser": "Chrome",
      "os": "Windows",
      "device": "Desktop",
      "country": "United States",
      "duration": 120,
      "lastSeen": "2024-01-15T10:30:00Z"
    }
  ],
  "pages": [
    {
      "path": "/dashboard",
      "title": "Dashboard",
      "count": 3
    },
    {
      "path": "/analytics",
      "title": "Analytics",
      "count": 2
    }
  ],
  "referrers": [
    {
      "domain": "google.com",
      "count": 2
    },
    {
      "domain": "twitter.com",
      "count": 1
    }
  ],
  "devices": [
    {
      "name": "Desktop",
      "count": 3
    },
    {
      "name": "Mobile",
      "count": 2
    }
  ],
  "countries": [
    {
      "name": "United States",
      "count": 3
    },
    {
      "name": "Canada",
      "count": 2
    }
  ]
}

Usage Examples

Real-time Dashboard (Last 5 minutes)

Perfect for live dashboards showing current website activity.

curl -X GET \
  "https://app.usehardal.com/api/websites/${SIGNAL_ID}/active" \
  -H "Authorization: Bearer ${API_KEY}" \
  -H "Content-Type: application/json"

Response:

{
  "count": 3,
  "visitors": [
    {
      "id": "session_abc123",
      "sessionId": "session_abc123",
      "page": "/dashboard",
      "title": "Dashboard - My App",
      "referrer": "https://google.com",
      "browser": "Chrome",
      "os": "Windows",
      "device": "Desktop",
      "country": "United States",
      "duration": 120,
      "lastSeen": "2024-01-15T10:30:00Z"
    }
  ],
  "pages": [
    {
      "path": "/dashboard",
      "title": "Dashboard",
      "count": 2
    }
  ],
  "referrers": [
    {
      "domain": "google.com",
      "count": 2
    }
  ],
  "devices": [
    {
      "name": "Desktop",
      "count": 2
    }
  ],
  "countries": [
    {
      "name": "United States",
      "count": 2
    }
  ]
}

Use Case: Live visitor counter, real-time dashboard widgets

Extended Activity Window (Last 30 minutes)

Get a broader view of recent activity for trend analysis.

curl -X GET \
  "https://app.usehardal.com/api/websites/${SIGNAL_ID}/active?minutes=30" \
  -H "Authorization: Bearer ${API_KEY}" \
  -H "Content-Type: application/json"

Response:

{
  "count": 8,
  "visitors": [
    {
      "id": "session_abc123",
      "sessionId": "session_abc123",
      "page": "/products",
      "title": "Products - Store",
      "referrer": "https://google.com",
      "browser": "Chrome",
      "os": "Windows",
      "device": "Desktop",
      "country": "United States",
      "duration": 300,
      "lastSeen": "2024-01-15T10:30:00Z"
    },
    {
      "id": "session_def456",
      "sessionId": "session_def456",
      "page": "/checkout",
      "title": "Checkout - Store",
      "referrer": "/products",
      "browser": "Safari",
      "os": "macOS",
      "device": "Desktop",
      "country": "Canada",
      "duration": 180,
      "lastSeen": "2024-01-15T10:28:00Z"
    }
  ],
  "pages": [
    {
      "path": "/products",
      "title": "Products",
      "count": 4
    },
    {
      "path": "/checkout",
      "title": "Checkout",
      "count": 2
    }
  ],
  "referrers": [
    {
      "domain": "google.com",
      "count": 5
    },
    {
      "domain": "twitter.com",
      "count": 2
    }
  ],
  "devices": [
    {
      "name": "Desktop",
      "count": 6
    },
    {
      "name": "Mobile",
      "count": 2
    }
  ],
  "countries": [
    {
      "name": "United States",
      "count": 5
    },
    {
      "name": "Canada",
      "count": 3
    }
  ]
}

Use Case: Traffic pattern analysis, identifying peak activity periods

Complete Configuration

Full parameter example with all options specified.

curl -X GET \
  "https://app.usehardal.com/api/websites/${SIGNAL_ID}/active?minutes=15&targetSignalId=${SIGNAL_ID}&isHybrid=false" \
  -H "Authorization: Bearer ${API_KEY}" \
  -H "Content-Type: application/json"

Response:

{
  "count": 5,
  "visitors": [
    {
      "id": "session_abc123",
      "sessionId": "session_abc123",
      "page": "/dashboard",
      "title": "Dashboard - My App",
      "referrer": "https://google.com",
      "browser": "Chrome",
      "os": "Windows",
      "device": "Desktop",
      "country": "United States",
      "duration": 120,
      "lastSeen": "2024-01-15T10:30:00Z"
    }
  ],
  "pages": [
    {
      "path": "/dashboard",
      "title": "Dashboard",
      "count": 3
    },
    {
      "path": "/analytics",
      "title": "Analytics",
      "count": 2
    }
  ],
  "referrers": [
    {
      "domain": "google.com",
      "count": 2
    },
    {
      "domain": "twitter.com",
      "count": 1
    }
  ],
  "devices": [
    {
      "name": "Desktop",
      "count": 3
    },
    {
      "name": "Mobile",
      "count": 2
    }
  ],
  "countries": [
    {
      "name": "United States",
      "count": 3
    },
    {
      "name": "Canada",
      "count": 2
    }
  ]
}

Use Case: Custom integrations with specific tracking requirements

Response Fields

Main Data

count: Total number of active unique sessions
visitors: Array of individual active visitor objects
pages: Top pages currently being viewed
referrers: Top referrer domains for active visitors
devices: Breakdown of device types
countries: Geographic distribution of active visitors

Visitor Object

id: Unique visitor identifier (session-based)
sessionId: Unique session identifier
page: Current page URL path
title: Current page title
referrer: Original referrer URL
browser: Browser name (Chrome, Safari, Firefox)
os: Operating system (Windows, macOS, Linux)
device: Device type (Desktop, Mobile, Tablet)
country: Country name
duration: Total time spent on site in seconds
lastSeen: Timestamp of last activity

Getting Started

Setup

Analytics

Server-side Hosts

Connections

ETL/Data Governance

FAQ

Changelog

Active Users API

Overview

Endpoint

Authentication

Parameters

Quick Start

Environment Setup

Usage Examples

Response Fields

Main Data

Visitor Object

Getting Started

Setup

Analytics

Server-side Hosts

Connections

ETL/Data Governance

FAQ

Changelog

​Overview

​Endpoint

​Authentication

​Parameters

​Quick Start

​Environment Setup

​Usage Examples

​Response Fields

​Main Data

​Visitor Object

Overview

Endpoint

Authentication

Parameters

Quick Start

Environment Setup

Usage Examples

Response Fields

Main Data

Visitor Object