Skip to main content

​
Overview

Custom events allow you to track user interactions beyond pageviews. Query event data, analyze event properties, and understand user behavior patterns.

​
Query Types

​
Custom Events

Get an overview of all custom events tracked on your website. Query Type: custom_events 
curl -X POST 'https://api.databuddy.com/v1/query?website_id=web_abc123' \
  -H 'Authorization: Bearer db_key_...' \
  -H 'Content-Type: application/json' \
  -d '{
    "parameters": ["custom_events"],
    "startDate": "2024-01-01",
    "endDate": "2024-01-31",
    "limit": 100
  }'
Response Fields:
​
name
string
The event name (e.g., button_click, form_submit).
​
total_events
number
Total number of times this event was triggered.
​
unique_users
number
Number of unique users who triggered this event.
​
unique_sessions
number
Number of unique sessions containing this event.
​
first_occurrence
string
Timestamp of the first occurrence of this event.
​
last_occurrence
string
Timestamp of the most recent occurrence.
​
events_with_properties
number
Number of events that include custom properties.
​
percentage
number
Percentage of unique users relative to total.

​
Custom Event Properties

Analyze properties attached to custom events to understand event context. Query Type: custom_event_properties 
curl -X POST 'https://api.databuddy.com/v1/query?website_id=web_abc123' \
  -H 'Authorization: Bearer db_key_...' \
  -H 'Content-Type: application/json' \
  -d '{
    "parameters": ["custom_event_properties"],
    "startDate": "2024-01-01",
    "endDate": "2024-01-31",
    "filters": [
      {
        "field": "event_name",
        "op": "eq",
        "value": "button_click"
      }
    ],
    "limit": 100
  }'
Response Fields:
​
name
string
The event name.
​
property_key
string
The property key name.
​
property_value
string
The property value.
​
count
number
Number of events with this property value.

​
Events by Path

See which pages generate the most custom events. Query Type: custom_events_by_path 
curl -X POST 'https://api.databuddy.com/v1/query?website_id=web_abc123' \
  -H 'Authorization: Bearer db_key_...' \
  -H 'Content-Type: application/json' \
  -d '{
    "parameters": ["custom_events_by_path"],
    "preset": "last_7d",
    "limit": 50
  }'
Response Fields:
​
name
string
The page path where events occurred.
​
total_events
number
Total events on this page.
​
unique_event_types
number
Number of different event types triggered on this page.
​
unique_users
number
Unique users who triggered events on this page.
Track event volume over time to identify patterns. Query Type: custom_events_trends 
curl -X POST 'https://api.databuddy.com/v1/query?website_id=web_abc123' \
  -H 'Authorization: Bearer db_key_...' \
  -H 'Content-Type: application/json' \
  -d '{
    "parameters": ["custom_events_trends"],
    "startDate": "2024-01-01",
    "endDate": "2024-01-31"
  }'
Response Fields:
​
date
string
Date of the data point (YYYY-MM-DD).
​
total_events
number
Total events on this date.
​
unique_event_types
number
Number of different event types.
​
unique_users
number
Unique users who triggered events.
​
unique_sessions
number
Unique sessions with events.
​
unique_pages
number
Number of different pages with events.

​
Events Summary

Get aggregate statistics for all events in a date range. Query Type: custom_events_summary 
curl -X POST 'https://api.databuddy.com/v1/query?website_id=web_abc123' \
  -H 'Authorization: Bearer db_key_...' \
  -H 'Content-Type: application/json' \
  -d '{
    "parameters": ["custom_events_summary"],
    "preset": "last_30d"
  }'
Response Fields:
​
total_events
number
Total event count.
​
unique_event_types
number
Number of different event types.
​
unique_users
number
Users who triggered events.
​
unique_sessions
number
Sessions containing events.
​
unique_pages
number
Pages with events.

​
Recent Events

View the most recent custom events with full details. Query Type: custom_events_recent 
curl -X POST 'https://api.databuddy.com/v1/query?website_id=web_abc123' \
  -H 'Authorization: Bearer db_key_...' \
  -H 'Content-Type: application/json' \
  -d '{
    "parameters": ["custom_events_recent"],
    "preset": "today",
    "limit": 50
  }'
Response Fields:
​
event_name
string
Name of the event.
​
namespace
string
Event namespace for grouping.
​
path
string
Page path where event occurred.
​
source
string
Event source (e.g., web, mobile).
​
properties
string
JSON string of event properties.
​
anonymous_id
string
Anonymous user identifier.
​
session_id
string
Session identifier.
​
timestamp
string
Event timestamp.

​
Events Discovery

Comprehensive query that returns events with their properties and top values in a single request. Query Type: custom_events_discovery 
curl -X POST 'https://api.databuddy.com/v1/query?website_id=web_abc123' \
  -H 'Authorization: Bearer db_key_...' \
  -H 'Content-Type: application/json' \
  -d '{
    "parameters": ["custom_events_discovery"],
    "preset": "last_7d",
    "limit": 200
  }'
Response Fields:
​
event_name
string
Name of the event.
​
total_events
number
Total event count.
​
unique_users
number
Unique users.
​
unique_sessions
number
Unique sessions.
​
property_key
string
Property key name (null if no properties).
​
unique_values
number
Number of unique values for this property.
​
top_values
array
Array of tuples containing top 5 property values and their counts.

​
Filters

Event queries support these filters:
​
namespace
string
Filter by event namespace.
​
website_id
string
Filter by specific website (for organization-level queries).
​
anonymous_id
string
Filter by user ID.
​
session_id
string
Filter by session ID.
​
event_name
string
Filter by event name.
​
source
string
Filter by event source.
​
path
string
Filter by page path.
​
property_key
string
Filter by property key name (for property queries).

​
Advanced Property Analysis

Analyze event property cardinality and classification: Property Cardinality (custom_events_property_cardinality): 
curl -X POST 'https://api.databuddy.com/v1/query?website_id=web_abc123' \
  -H 'Authorization: Bearer db_key_...' \
  -H 'Content-Type: application/json' \
  -d '{
    "parameters": ["custom_events_property_cardinality"],
    "preset": "last_30d",
    "filters": [
      {"field": "event_name", "op": "eq", "value": "button_click"}
    ]
  }'
Property Top Values (custom_events_property_top_values): 
curl -X POST 'https://api.databuddy.com/v1/query?website_id=web_abc123' \
  -H 'Authorization: Bearer db_key_...' \
  -H 'Content-Type: application/json' \
  -d '{
    "parameters": ["custom_events_property_top_values"],
    "preset": "last_7d",
    "filters": [
      {"field": "event_name", "op": "eq", "value": "button_click"},
      {"field": "property_key", "op": "eq", "value": "button_id"}
    ],
    "limit": 10
  }'
Property Distribution (custom_events_property_distribution): 
curl -X POST 'https://api.databuddy.com/v1/query?website_id=web_abc123' \
  -H 'Authorization: Bearer db_key_...' \
  -H 'Content-Type: application/json' \
  -d '{
    "parameters": ["custom_events_property_distribution"],
    "preset": "last_30d",
    "filters": [
      {"field": "property_key", "op": "eq", "value": "plan_type"}
    ]
  }'

​
Notes

  • Custom events are stored separately from pageview events
  • Events can include arbitrary JSON properties for rich context
  • Property queries automatically extract and analyze JSON property keys and values
  • Event properties support filtering by both the property key and value
  • The discovery query is optimized for exploring your event schema

Build docs developers (and LLMs) love

Get started for freeTalk to us