Skip to main content
The Events API provides endpoints to analyze custom events tracked in your application.

​
Get event names

GET /api/websites/:id/events Retrieve a list of all custom event names tracked for a website.

​
Path parameters

​
id
string
required
Website ID (format: site_XXXXXXXXXX)

​
Query parameters

​
start_date
string
Start date (YYYY-MM-DD). Defaults to 7 days ago.
​
end_date
string
End date (YYYY-MM-DD). Defaults to today.
​
timezone
string
Timezone for date range (e.g., America/New_York). Defaults to UTC.
​
include_bots
boolean
Include bot traffic. Defaults to false.
All standard filters are supported: filter_country, filter_page, filter_referrer, filter_browser, filter_os, filter_device, filter_language, filter_utm_source, filter_utm_medium, filter_utm_campaign, filter_region, filter_city, filter_hostname.
Maximum date range: 90 days

​
Response

​
events
array
Array of event name strings

​
Example

curl -X GET "https://analytics.example.com/api/websites/site_abc123/events?start_date=2026-03-01&end_date=2026-03-07" \
  -H "Authorization: Bearer spk_selfhosted_abc123..."
Response
{
  "events": [
    "signup_click",
    "purchase",
    "video_play",
    "form_submit"
  ]
}

​
Get event properties

GET /api/websites/:id/events/properties Retrieve event property keys and sample values for a specific event.

​
Query parameters

​
event_name
string
required
Event name to query properties for
All date range and filter parameters from the event names endpoint are also supported.

​
Response

​
properties
object
Object mapping property keys to arrays of sample values

​
Example

curl -X GET "https://analytics.example.com/api/websites/site_abc123/events/properties?event_name=purchase" \
  -H "Authorization: Bearer spk_selfhosted_abc123..."
Response
{
  "properties": {
    "product": ["Pro Plan", "Team Plan", "Enterprise"],
    "amount": ["29.99", "99.99", "299.99"],
    "currency": ["USD", "EUR"]
  }
}

​
Get event time series

GET /api/websites/:id/events/timeseries Retrieve event counts over time for a specific event.

​
Query parameters

​
event_name
string
required
Event name to query time series for
​
granularity
string
Time bucket size: hour, day, week, month. Defaults to day.
All date range and filter parameters are also supported.

​
Response

​
series
array
Array of time series data points

​
Example

curl -X GET "https://analytics.example.com/api/websites/site_abc123/events/timeseries?event_name=signup_click&granularity=day" \
  -H "Authorization: Bearer spk_selfhosted_abc123..."
Response
{
  "series": [
    {"timestamp": "2026-03-01T00:00:00Z", "count": 45},
    {"timestamp": "2026-03-02T00:00:00Z", "count": 52},
    {"timestamp": "2026-03-03T00:00:00Z", "count": 38}
  ]
}

​
Use cases

Event Analytics Dashboard

Build custom event dashboards showing trends for specific user actions

Property Analysis

Analyze event properties to understand user behavior patterns

Conversion Tracking

Track specific conversion events across different segments

Feature Adoption

Monitor adoption of new features via custom event tracking

Build docs developers (and LLMs) love

Get started for freeTalk to us