Getting Started
Setup
- Quickstart
- DNS Settings
- Website
- iOS
- Android
- Gaming
- Self-Hosted
Server-side Hosts
- Hosts
- Google
- Meta
- Tiktok
Connections
- Overview
- Google
- Meta
- Tiktok
- Adjust
- LinkedIn
- Zapier
- Firebase
- Insider
- Segmentify
- Custom API
- More
Analytics
- Basics
- Custom Events
- Custom Metrics
- Data Structure
- Analytics API
ETL/Data Governance
- Data Governance
- PII Hashing
- Looker Studio
- BigQuery
- Hex
Changelog
Analytics API
API Reference
Analytics API
API Reference
Documentation for the Hardal Analytics API endpoints
Overview
The Hardal Analytics API provides programmatic access to your website analytics data. These endpoints allow you to retrieve statistics, real-time data, session information, and more for integration with custom dashboards or applications.
All API requests require authentication using an API key that can be generated in your Hardal dashboard settings.
Authentication
Include your API key in the request header:
Authorization: Bearer YOUR_API_KEY
Protect your API key and never expose it in client-side code. All API requests should be made server-side.
Endpoints
Website Statistics
Returns basic website statistics.
Parameters:
websiteId(path): ID of the websitestartDate(query, optional): Starting date for data range (YYYY-MM-DD)endDate(query, optional): Ending date for data range (YYYY-MM-DD)
Response:
{
"sessions": 12450,
"events": 45320,
"pageviews": 28740
}
Returns detailed statistics with current and previous period comparisons.
Parameters:
websiteId(path): ID of the websitestartAt,endAt(query, optional): Date range (YYYY-MM-DD)- Optional filters (query):
url,referrer,title,query,event,host,os, etc.
Response:
{
"pageviews": {
"value": 28740,
"change": 5.2
},
"visitors": {
"value": 8920,
"change": 3.7
},
"visits": {
"value": 12450,
"change": 4.1
},
"bounce_rate": {
"value": 42.3,
"change": -2.1
},
"avg_session_duration": {
"value": 124,
"change": 8.5
}
}
Chart Data
Returns time-series data for charts.
Parameters:
websiteId(path): ID of the websitestartDate,endDate(query, optional): Date range (YYYY-MM-DD)timeframe(query, optional): Predefined timeframes like ‘today’, ‘yesterday’, ‘last7days’, etc.interval(query, optional): Time granularity - ‘hourly’, ‘daily’, or ‘auto’
Response:
{
"labels": ["2023-04-01", "2023-04-02", "..."],
"datasets": {
"pageviews": [1240, 1350, "..."],
"sessions": [820, 940, "..."],
"visitors": [750, 820, "..."]
}
}
Real-time Data
Returns active visitors and related metrics.
Parameters:
websiteId(path): ID of the websiteminutes(query, optional): Time window for active visitors (default: 5)
Response:
{
"active": 42,
"visitors": [
{
"session_id": "...",
"country": "US",
"device": "desktop",
"current_page": "/products"
},
"..."
],
"top_pages": [
{ "url": "/products", "count": 12 },
"..."
],
"top_referrers": [
{ "referrer": "google.com", "count": 18 },
"..."
],
"top_devices": [
{ "device": "desktop", "count": 28 },
"..."
],
"top_countries": [
{ "country": "US", "count": 22 },
"..."
]
}
Sessions & Events
Returns a list of sessions.
Parameters:
websiteId(path): ID of the websitepage(query, optional): Page number for paginationlimit(query, optional): Results per page (default: 50, max: 100)startDate,endDate(query, optional): Date range- Optional filters (query):
country,device,os,browser, etc.
Response:
{
"sessions": [
{
"session_id": "...",
"visitor_id": "...",
"started_at": "2023-04-01T14:22:53Z",
"duration": 245,
"pages": 4,
"events": 12,
"country": "US",
"device": "desktop",
"os": "Windows",
"browser": "Chrome"
},
"..."
],
"pagination": {
"page": 1,
"limit": 50,
"total": 1240
}
}
Returns detailed data for a specific session.
Parameters:
websiteId(path): ID of the websitesessionId(path): ID of the session
Response:
{
"session_id": "...",
"visitor_id": "...",
"started_at": "2023-04-01T14:22:53Z",
"duration": 245,
"country": "US",
"device": "desktop",
"os": "Windows",
"browser": "Chrome",
"referrer": "google.com",
"utm_source": "google",
"utm_medium": "cpc",
"utm_campaign": "spring_sale",
"pageviews": [
{
"url": "/",
"title": "Homepage",
"timestamp": "2023-04-01T14:22:53Z",
"duration": 45
},
"..."
],
"events": [
{
"name": "click",
"timestamp": "2023-04-01T14:23:17Z",
"properties": {
"element": "button",
"id": "add-to-cart"
}
},
"..."
]
}
Returns activity data for a specific session.
Parameters:
websiteId(path): ID of the websitesessionId(path): ID of the session
Response:
{
"session_id": "...",
"activities": [
{
"type": "pageview",
"timestamp": "2023-04-01T14:22:53Z",
"data": {
"url": "/",
"title": "Homepage"
}
},
{
"type": "event",
"timestamp": "2023-04-01T14:23:17Z",
"data": {
"name": "click",
"properties": {
"element": "button",
"id": "add-to-cart"
}
}
},
"..."
]
}
Returns events with optional grouping.
Parameters:
websiteId(path): ID of the websitepage,limit(query, optional): Pagination parametersstartDate,endDate(query, optional): Date rangegroupBy(query, optional): Group by ‘event’ or return raw events
Response (when groupBy=event):
{
"events": [
{
"name": "click",
"count": 8240
},
{
"name": "form_submit",
"count": 1450
},
"..."
],
"pagination": {
"page": 1,
"limit": 50,
"total": 12
}
}
Response (raw events):
{
"events": [
{
"id": "...",
"session_id": "...",
"name": "click",
"timestamp": "2023-04-01T14:23:17Z",
"properties": {
"element": "button",
"id": "add-to-cart"
}
},
"..."
],
"pagination": {
"page": 1,
"limit": 50,
"total": 8240
}
}
Returns pageview data with optional grouping.
Parameters:
websiteId(path): ID of the websitepage,limit(query, optional): Pagination parametersstartDate,endDate(query, optional): Date rangegroupBy(query, optional): Group by ‘url’, ‘referrer’, or ‘time’
Response (when groupBy=url):
{
"pageviews": [
{
"url": "/products",
"views": 4520,
"visitors": 3240,
"avg_time": 85
},
"..."
],
"pagination": {
"page": 1,
"limit": 50,
"total": 245
}
}
Metrics & Analysis
Returns comprehensive metrics for analytics dashboards.
Parameters:
websiteId(path): ID of the websitestartDate,endDate(query, optional): Date range- Optional filters (query): Various filter parameters
Response:
{
"summary": {
"pageviews": 28740,
"visitors": 8920,
"sessions": 12450,
"bounce_rate": 42.3,
"avg_session_duration": 124
},
"timeseries": {
"labels": ["2023-04-01", "2023-04-02", "..."],
"pageviews": [1240, 1350, "..."],
"visitors": [750, 820, "..."]
},
"countries": [
{ "code": "US", "count": 4520, "percentage": 38.5 },
"..."
],
"browsers": [
{ "name": "Chrome", "count": 7840, "percentage": 62.4 },
"..."
],
"os": [
{ "name": "Windows", "count": 5420, "percentage": 43.2 },
"..."
],
"devices": [
{ "type": "desktop", "count": 8240, "percentage": 65.6 },
"..."
],
"pages": [
{ "url": "/products", "views": 4520, "visitors": 3240 },
"..."
],
"referrers": [
{ "domain": "google.com", "count": 3840, "percentage": 30.6 },
"..."
]
}
Returns UTM campaign data and conversion metrics.
Parameters:
websiteId(path): ID of the websitestartDate,endDate(query, optional): Date rangeconversion_event(query, optional): Event to track as conversion
Response:
{
"campaigns": [
{
"utm_source": "google",
"utm_medium": "cpc",
"utm_campaign": "spring_sale",
"sessions": 1240,
"visitors": 980,
"conversions": 124,
"conversion_rate": 12.6
},
"..."
]
}
Returns event data fields for analysis.
Parameters:
websiteId(path): ID of the websitestartDate,endDate(query, optional): Date rangeeventName(query, optional): Filter by specific event
Response:
{
"events": [
"add_to_cart",
"checkout",
"purchase"
],
"fields": {
"add_to_cart": [
"product_id",
"product_name",
"price",
"quantity"
],
"checkout": [
"cart_value",
"products_count",
"coupon_code"
],
"purchase": [
"order_id",
"total_value",
"products"
]
}
}
Error Handling
The API uses standard HTTP status codes and returns error details in the response body:
{
"error": {
"code": 401,
"message": "Invalid API key"
}
}
Rate Limits
API requests are limited to 100 requests per minute per API key. Exceeding this limit will result in a 429 status code.
Data Retention
API data reflects the same retention policy as your Hardal Analytics account settings.
Using the API
Sample Request with cURL
curl -X GET "https://<yourcustomsignaldomain.com>/website/123456/stats?startAt=2023-04-01&endAt=2023-04-30" \
-H "Authorization: Bearer YOUR_API_KEY"
Sample Request with JavaScript
const fetchStats = async () => {
const response = await fetch('https://<yourcustomsignaldomain.com>/website/123456/stats?startAt=2023-04-01&endAt=2023-04-30', {
headers: {
'Authorization': 'Bearer YOUR_API_KEY'
}
});
if (!response.ok) {
const error = await response.json();
throw new Error(error.message || 'Failed to fetch stats');
}
return await response.json();
};