Event Data Fields API

Overview

The Event Data Fields endpoint provides comprehensive access to your event data with all custom fields and attribution information. Perfect for analyzing conversion events, e-commerce transactions, user interactions, and building detailed event analytics with marketing attribution.

Get granular insights into user behavior with full event properties, UTM attribution, and flexible filtering options for any event type you track.

Endpoint

GET https://app.usehardal.com/api/websites/{signalId}/event-data/fields

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)
`targetSignalId`	string	Yes	-	Target signal ID for analytics data
`isHybrid`	boolean	Yes	-	Whether the signal uses hybrid tracking
`eventName`	string	Yes	-	Name of the event to fetch data for
`startDate`	string	No	-	Start date for data range (ISO format)
`endDate`	string	No	-	End date for data range (ISO format)
`timeframe`	string	No	custom	Time period: `today`, `yesterday`, `last7days`, `last30days`, `custom`
`timezone`	string	No	UTC	Timezone for date calculations (URL encoded)
`attribution_model`	string	No	last_click	Attribution model (see below)
`attribution_window`	number	No	30	Attribution window in days
`limit`	number	No	50	Number of events to return
`offset`	number	No	0	Pagination offset

Quick Start

Environment Setup

Finding your signal ID: Go to your Hardal dashboard → select your project → view the signal ID in settings.

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

Start with a simple request to get purchase event data:

Basic Purchase Events

Get today’s purchase events with attribution data.

curl -X GET \
  "https://app.usehardal.com/api/websites/${SIGNAL_ID}/event-data/fields?eventName=purchase&timeframe=today&timezone=Asia%2FIstanbul&attribution_model=last_click&attribution_window=30&limit=10&offset=0&targetSignalId=${SIGNAL_ID}&isHybrid=false" \
  -H "Authorization: Bearer YOUR_API_KEY"

Response:

{
  "data": [
    {
      "session_id": "b4660049363c5c1a5e3e2d0088386aee",
      "event_id": "evt_6789abcdef",
      "created_at": "2025-07-02T10:30:45.000Z",
      "event_name": "purchase",
      "value": 99.99,
      "currency": "TRY",
      "product_id": "prod_123",
      "product_name": "Premium Subscription",
      "category": "subscription",
      "quantity": 1,
      "user_email": "user@example.com",
      "source": "google",
      "medium": "cpc",
      "campaign": "summer_sale"
    }
  ],
  "pagination": {
    "total": 127,
    "totalPages": 13,
    "currentPage": 1,
    "limit": 10,
    "offset": 0,
    "hasNextPage": true,
    "hasPreviousPage": false
  }
}

Usage Examples

Today's Purchase Events

Get all purchase events from today with full attribution data.

curl -X GET \
  "https://app.usehardal.com/api/websites/${SIGNAL_ID}/event-data/fields?eventName=purchase&timeframe=today&timezone=Asia%2FIstanbul&attribution_model=last_click&attribution_window=30&limit=10&offset=0&targetSignalId=${SIGNAL_ID}&isHybrid=false" \
  -H "Authorization: Bearer YOUR_API_KEY"

Response:

{
  "data": [
    {
      "session_id": "b4660049363c5c1a5e3e2d0088386aee",
      "event_id": "evt_6789abcdef",
      "created_at": "2025-07-02T10:30:45.000Z",
      "event_name": "purchase",
      "value": 99.99,
      "currency": "TRY",
      "product_id": "prod_123",
      "product_name": "Premium Subscription",
      "category": "subscription",
      "quantity": 1,
      "user_email": "user@example.com",
      "source": "google",
      "medium": "cpc",
      "campaign": "summer_sale"
    }
  ],
  "pagination": {
    "total": 127,
    "totalPages": 13,
    "currentPage": 1,
    "limit": 10,
    "offset": 0,
    "hasNextPage": true,
    "hasPreviousPage": false
  }
}

Use Case: E-commerce revenue tracking, conversion analysis

Custom Date Range Analysis

Analyze events within a specific date range for detailed reporting.

curl -X GET \
  "https://app.usehardal.com/api/websites/${SIGNAL_ID}/event-data/fields?eventName=purchase&startDate=2025-06-25T01%3A04%3A54&endDate=2025-06-26T00%3A00%3A00&timezone=Asia%2FIstanbul&attribution_model=last_click&attribution_window=30&limit=10&offset=0&targetSignalId=${SIGNAL_ID}&isHybrid=false" \
  -H "Authorization: Bearer YOUR_API_KEY"

Response:

{
  "data": [
    {
      "session_id": "a1234567890abcdef123456789",
      "event_id": "evt_abcd1234",
      "created_at": "2025-06-25T09:15:22.000Z",
      "event_name": "purchase",
      "value": 149.99,
      "currency": "TRY",
      "product_id": "prod_456",
      "product_name": "Annual Plan",
      "category": "subscription",
      "quantity": 1,
      "user_email": "customer@example.com",
      "source": "facebook",
      "medium": "social",
      "campaign": "retargeting"
    }
  ],
  "pagination": {
    "total": 85,
    "totalPages": 9,
    "currentPage": 1,
    "limit": 10,
    "offset": 0,
    "hasNextPage": true,
    "hasPreviousPage": false
  }
}

Use Case: Historical analysis, campaign performance review

Signup Events - Last 7 Days

Track user registrations and signups over the past week.

curl -X GET \
  "https://app.usehardal.com/api/websites/${SIGNAL_ID}/event-data/fields?eventName=signup&timeframe=last7days&timezone=Asia%2FIstanbul&attribution_model=last_click&attribution_window=30&limit=20&offset=0&targetSignalId=${SIGNAL_ID}&isHybrid=false" \
  -H "Authorization: Bearer YOUR_API_KEY"

Response:

{
  "data": [
    {
      "session_id": "signup_session_123",
      "event_id": "evt_signup_001",
      "created_at": "2025-07-01T14:22:33.000Z",
      "event_name": "signup",
      "user_email": "newuser@example.com",
      "user_id": "user_789",
      "signup_method": "email",
      "plan_type": "free",
      "source": "google",
      "medium": "organic",
      "campaign": null
    },
    {
      "session_id": "signup_session_456",
      "event_id": "evt_signup_002",
      "created_at": "2025-07-01T11:45:15.000Z",
      "event_name": "signup",
      "user_email": "premium@example.com",
      "user_id": "user_890",
      "signup_method": "google_oauth",
      "plan_type": "premium",
      "source": "facebook",
      "medium": "cpc",
      "campaign": "acquisition"
    }
  ],
  "pagination": {
    "total": 45,
    "totalPages": 3,
    "currentPage": 1,
    "limit": 20,
    "offset": 0,
    "hasNextPage": true,
    "hasPreviousPage": false
  }
}

Use Case: User acquisition analysis, signup funnel optimization

Paginated Event Data

Handle large datasets with pagination for comprehensive analysis.

# Get second page of results
curl -X GET \
  "https://app.usehardal.com/api/websites/${SIGNAL_ID}/event-data/fields?eventName=purchase&timeframe=today&timezone=Asia%2FIstanbul&attribution_model=last_click&attribution_window=30&limit=10&offset=10&targetSignalId=${SIGNAL_ID}&isHybrid=false" \
  -H "Authorization: Bearer YOUR_API_KEY"

Response:

{
  "data": [
    {
      "session_id": "page2_session_001",
      "event_id": "evt_page2_001",
      "created_at": "2025-07-02T08:15:30.000Z",
      "event_name": "purchase",
      "value": 59.99,
      "currency": "TRY",
      "product_id": "prod_789",
      "product_name": "Basic Plan",
      "category": "subscription",
      "quantity": 1,
      "user_email": "basic@example.com",
      "source": "twitter",
      "medium": "social",
      "campaign": "social_media"
    }
  ],
  "pagination": {
    "total": 127,
    "totalPages": 13,
    "currentPage": 2,
    "limit": 10,
    "offset": 10,
    "hasNextPage": true,
    "hasPreviousPage": true
  }
}

Use Case: Data export, comprehensive reporting, ETL processes

Response Fields

Standard Fields

session_id: Unique session identifier
event_id: Unique event identifier
created_at: Event timestamp (ISO format)
event_name: Name of the event

Attribution Fields

source: UTM source or traffic source
medium: UTM medium or traffic medium
campaign: UTM campaign name

Custom Event Fields

The response includes all custom fields tracked with the event:

E-commerce Events

value: Purchase amount or event value
currency: Currency code (USD, EUR, TRY, etc.)
product_id: Product identifier
product_name: Product name or title
category: Product category
quantity: Number of items
discount: Discount amount applied

User Events

user_email: User email address
user_id: User identifier
user_name: User display name
subscription_type: Type of subscription

Marketing Events

promotion_id: Promotion identifier
coupon_code: Applied coupon code
affiliate_id: Affiliate tracking ID

Pagination Object

total: Total number of events matching criteria
totalPages: Total number of pages
currentPage: Current page number (1-based)
limit: Number of events per page
offset: Current pagination offset
hasNextPage: Whether more pages exist
hasPreviousPage: Whether previous pages exist

Attribution Models

Choose the attribution model that best fits your marketing analysis:

Model	Description	Best For
`last_click`	Credit to the last touchpoint before event	Direct response campaigns
`first_click`	Credit to the first touchpoint in journey	Brand awareness campaigns
`any_click`	Credit to any touchpoint that influenced event	General attribution
`linear`	Equal credit across all touchpoints	Multi-touch campaigns
`time_decay`	More credit to recent touchpoints	Complex customer journeys

Data Type Handling

The endpoint automatically handles different data types in your custom fields:

Primitive Values

JSON Arrays (Flattened)

JSON Objects (Flattened)

Performance Considerations

Query Performance Notice: This endpoint performs complex queries with custom fields and attribution modeling. Query time increases significantly with larger date ranges.

For optimal performance:

Use shorter date ranges (1-7 days) for detailed event analysis
Use longer date ranges (30+ days) sparingly for historical exports
Consider smaller limit values (10-50) for large datasets
Peak performance with today and yesterday timeframes
Filter by specific eventName to reduce query complexity

Usage Notes

Event Name Required: Must specify an eventName parameter to filter events
Custom Fields: All custom event properties are included in the response
Attribution Data: Each event includes marketing attribution information
Array Flattening: JSON arrays and objects are flattened with dot notation
Timezone Support: All timestamps are converted to the specified timezone
Pagination: Use limit and offset for paginated results
Date Filtering: Supports both preset timeframes and custom date ranges

Getting Started

Setup

Analytics

Server-side Hosts

Connections

ETL/Data Governance

FAQ

Changelog

Event Data Fields API

Overview

Endpoint

Authentication

Parameters

Quick Start

Environment Setup

Usage Examples

Response Fields

Standard Fields

Attribution Fields

Custom Event Fields

E-commerce Events

User Events

Marketing Events

Attribution Models

Data Type Handling

Performance Considerations

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

​Standard Fields

​Attribution Fields

​Custom Event Fields

​E-commerce Events

​User Events

​Marketing Events

​Pagination Object

​Attribution Models

​Data Type Handling

​Performance Considerations

​Usage Notes

Overview

Endpoint

Authentication

Parameters

Quick Start

Environment Setup

Usage Examples

Response Fields

Standard Fields

Attribution Fields

Custom Event Fields

E-commerce Events

User Events

Marketing Events

Pagination Object

Attribution Models

Data Type Handling

Performance Considerations

Usage Notes