Events API

Overview

The Events endpoint provides access to detailed event data from your website analytics. Track custom events, page views, and user interactions with powerful filtering, grouping, and pagination capabilities.

Perfect for analyzing user behavior, conversion funnels, and custom event tracking across your website.

Endpoint

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

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)
`timeframe`	string	No	custom	Time period: `today`, `yesterday`, `last7days`, `last30days`, `custom`
`startDate`	string	No	-	Start date for timeframe (ISO format)
`endDate`	string	No	-	End date for timeframe (ISO format)
`timezone`	string	No	Europe/Istanbul	Timezone for date calculations (e.g., `Asia/Istanbul`)
`groupBy`	string	No	-	Group results: `event`, `date`
`limit`	integer	No	1000	Number of events to return (pagination)
`offset`	integer	No	0	Number of events to skip (pagination)
`targetSignalId`	string	No	signalId	Target signal ID for analytics data
`isHybrid`	boolean	No	false	Whether this is a hybrid/self-hosted signal
`eventName`	string	No	-	Filter by specific event name
`sessionId`	string	No	-	Filter by specific session ID

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 Events Request

Get recent events from your website.

curl -X GET \
  "https://app.usehardal.com/api/websites/${SIGNAL_ID}/events?limit=10" \
  -H "Authorization: Bearer YOUR_API_KEY" \
  -H "Content-Type: application/json"

Response:

{
  "events": [
    {
      "id": "evt_123456789",
      "website_id": "cm6gihhlq000aue9wkelb4ay3",
      "session_id": "sess_abc123",
      "hostname": "example.com",
      "browser": "Chrome",
      "os": "Windows",
      "device": "Desktop",
      "country": "Turkey",
      "url": "/products/item-1",
      "referrer": "https://google.com",
      "page_title": "Product Details",
      "event_type": "pageview",
      "event_name": "page_view",
      "created_at": "2024-01-15T10:30:00+03:00"
    }
  ],
  "pagination": {
    "total": 1250,
    "limit": 10,
    "offset": 0,
    "hasMore": true,
    "totalPages": 125,
    "currentPage": 1
  }
}

Usage Examples

Today's Events

Get all events that happened today.

curl -X GET \
  "https://app.usehardal.com/api/websites/${SIGNAL_ID}/events?timeframe=today&startDate=2025-07-01T00%3A00%3A00&endDate=2025-07-01T23%3A46%3A34&timezone=Asia%2FIstanbul&groupBy=date&limit=10&offset=0&targetSignalId=${SIGNAL_ID}&isHybrid=false" \
  -H "Authorization: Bearer YOUR_API_KEY" \
  -H "Content-Type: application/json"

Response:

{
  "events": [
    {
      "id": "evt_123456789",
      "website_id": "cm6gihhlq000aue9wkelb4ay3",
      "session_id": "sess_abc123",
      "hostname": "example.com",
      "browser": "Chrome",
      "os": "Windows",
      "device": "Desktop",
      "country": "Turkey",
      "url": "/products/item-1",
      "referrer": "https://google.com",
      "page_title": "Product Details",
      "event_type": "pageview",
      "event_name": "page_view",
      "created_at": "2024-01-15T10:30:00+03:00"
    }
  ],
  "pagination": {
    "total": 1250,
    "limit": 10,
    "offset": 0,
    "hasMore": true,
    "totalPages": 125,
    "currentPage": 1
  }
}

Use Case: Daily event monitoring, real-time activity tracking

Yesterday's Events

Get events from the previous day.

curl -X GET \
  "https://app.usehardal.com/api/websites/${SIGNAL_ID}/events?timeframe=yesterday&timezone=Asia%2FIstanbul&groupBy=date&limit=10&offset=0&targetSignalId=${SIGNAL_ID}&isHybrid=false" \
  -H "Authorization: Bearer YOUR_API_KEY" \
  -H "Content-Type: application/json"

Use Case: Daily reporting, yesterday’s performance analysis

Last 7 Days Events

Get events from the past week.

curl -X GET \
  "https://app.usehardal.com/api/websites/${SIGNAL_ID}/events?timeframe=last7days&timezone=Asia%2FIstanbul&groupBy=date&limit=10&offset=0&targetSignalId=${SIGNAL_ID}&isHybrid=false" \
  -H "Authorization: Bearer YOUR_API_KEY" \
  -H "Content-Type: application/json"

Use Case: Weekly trend analysis, user behavior patterns

Last 30 Days Events

Get events from the past month.

curl -X GET \
  "https://app.usehardal.com/api/websites/${SIGNAL_ID}/events?timeframe=last30days&timezone=Asia%2FIstanbul&groupBy=date&limit=10&offset=0&targetSignalId=${SIGNAL_ID}&isHybrid=false" \
  -H "Authorization: Bearer YOUR_API_KEY" \
  -H "Content-Type: application/json"

Use Case: Monthly reporting, long-term trend analysis

Custom Date Range

Get events from a specific date range.

curl -X GET \
  "https://app.usehardal.com/api/websites/${SIGNAL_ID}/events?startDate=2025-06-27T00%3A00%3A00&endDate=2025-06-28T00%3A00%3A00&timezone=Asia%2FIstanbul&groupBy=date&limit=10&offset=0&targetSignalId=${SIGNAL_ID}&isHybrid=false" \
  -H "Authorization: Bearer YOUR_API_KEY" \
  -H "Content-Type: application/json"

Use Case: Campaign analysis, specific period reporting

Event Counts (Group by Event)

Get aggregated event counts by event type.

curl -X GET \
  "https://app.usehardal.com/api/websites/${SIGNAL_ID}/events?timeframe=custom&startDate=2025-06-27T00%3A00%3A00&endDate=2025-06-28T00%3A00%3A00&timezone=Asia%2FIstanbul&groupBy=event&targetSignalId=${SIGNAL_ID}&isHybrid=false" \
  -H "Authorization: Bearer YOUR_API_KEY" \
  -H "Content-Type: application/json"

Response:

{
  "eventCounts": [
    {
      "name": "page_view",
      "count": 850,
      "unique_visitors": 320
    },
    {
      "name": "purchase",
      "count": 45,
      "unique_visitors": 40
    },
    {
      "name": "add_to_cart",
      "count": 120,
      "unique_visitors": 85
    }
  ],
  "totalEvents": 1015,
  "events": [],
  "pagination": {
    "total": 1015,
    "limit": 3,
    "offset": 0,
    "hasMore": false
  }
}

Use Case: Event performance analysis, conversion funnel tracking

Filter by Event Name

Get only purchase events.

curl -X GET \
  "https://app.usehardal.com/api/websites/${SIGNAL_ID}/events?startDate=2025-06-27T00%3A00%3A00&endDate=2025-06-28T00%3A00%3A00&timezone=Asia%2FIstanbul&groupBy=date&limit=10&offset=0&targetSignalId=${SIGNAL_ID}&isHybrid=false&eventName=purchase" \
  -H "Authorization: Bearer YOUR_API_KEY" \
  -H "Content-Type: application/json"

Use Case: Conversion tracking, specific event analysis

Response Fields

Event Object

id: Unique event identifier
website_id: Website/signal ID
session_id: Session identifier
hostname: Website hostname
browser: Browser name (Chrome, Safari, Firefox, etc.)
os: Operating system (Windows, macOS, Linux, etc.)
device: Device type (Desktop, Mobile, Tablet)
country: Country name
url: Page URL where event occurred
referrer: Referrer URL
page_title: Page title
event_type: Event type (pageview, custom, etc.)
event_name: Specific event name
created_at: Event timestamp

Pagination Object

total: Total number of events available
limit: Number of events requested
offset: Number of events skipped
hasMore: Whether there are more events available
totalPages: Total number of pages available
currentPage: Current page number (1-based)

Event Count Object (when groupBy=event)

name: Event name
count: Total number of occurrences
unique_visitors: Number of unique visitors who triggered this event

Pagination

The events endpoint supports pagination through limit and offset parameters:

Pagination Examples

Navigate through large event datasets efficiently.

# Get first page (events 0-9)
curl -X GET \
  "https://app.usehardal.com/api/websites/${SIGNAL_ID}/events?limit=10&offset=0" \
  -H "Authorization: Bearer YOUR_API_KEY"

# Get second page (events 10-19)
curl -X GET \
  "https://app.usehardal.com/api/websites/${SIGNAL_ID}/events?limit=10&offset=10" \
  -H "Authorization: Bearer YOUR_API_KEY"

# Get third page (events 20-29)
curl -X GET \
  "https://app.usehardal.com/api/websites/${SIGNAL_ID}/events?limit=10&offset=20" \
  -H "Authorization: Bearer YOUR_API_KEY"

Pagination Response:

{
  "events": [...],
  "pagination": {
    "total": 1250,
    "limit": 10,
    "offset": 20,
    "hasMore": true,
    "totalPages": 125,
    "currentPage": 3
  }
}

Timeframe Options

today: Current day from 00:00 to now
yesterday: Previous day (full 24 hours)
last7days: Last 7 days including today
last30days: Last 30 days including today
custom: Custom date range (requires startDate and endDate)

Usage Notes

Performance: Default limit is 1000 events if not specified. For large datasets, use pagination to avoid timeouts.

Ordering: Events are ordered by created_at timestamp in descending order (newest first).

Grouping: When groupBy=event is used, individual events are not returned; only event counts.

The timezone parameter affects how dates are interpreted and returned
All timestamps in responses are formatted according to the specified timezone
Pagination uses 1-based page numbering in the response
Large datasets may require multiple paginated requests to retrieve all events

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

Event Object

Event Count Object (when groupBy=event)

Timeframe Options

Usage Notes

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

​Event Object

​Pagination Object

​Event Count Object (when groupBy=event)

​Pagination

​Timeframe Options

​Usage Notes

Overview

Endpoint

Authentication

Parameters

Quick Start

Environment Setup

Usage Examples

Response Fields

Event Object

Pagination Object

Event Count Object (when groupBy=event)

Pagination

Timeframe Options

Usage Notes