Skip to main content
Events are the core of product analytics. When a user signs up, views a page, or makes a purchase, Tell records it as an event with a name and properties. The analytics engine lets you count events, rank them, break them down by property values, and run aggregations like sum and average.

​
Quick start

# Total event count over 30 days
tell metrics events --range 30d

# Top 10 most frequent events
tell metrics events --top --range 30d --limit 10
Via the API: 
curl "https://your-tell-server/api/v1/metrics/events?range=30d&granularity=daily" \
  -H "Authorization: Bearer $TOKEN"

​
Event counts

Count all events or filter to a specific event name: 
# All events over time
tell metrics events --range 7d

# Just sign_up events
tell metrics events --range 7d --event sign_up
API: 
# Count a specific event
curl "https://your-tell-server/api/v1/metrics/events?range=7d&event=sign_up" \
  -H "Authorization: Bearer $TOKEN"

​
Top events

See which events happen most often: 
curl "https://your-tell-server/api/v1/metrics/events/top?range=30d&limit=10" \
  -H "Authorization: Bearer $TOKEN"
Returns event names ranked by count, so you can quickly see what’s driving volume.

​
Property breakdowns

Break down a specific event by its properties to understand the distribution: 
# sign_up events broken down by plan property
curl "https://your-tell-server/api/v1/metrics/events/properties?range=30d&event=sign_up&property=properties.plan" \
  -H "Authorization: Bearer $TOKEN"
This returns time series data grouped by each property value (e.g., “free”, “pro”, “enterprise”). For top-level fields, use the field name directly (device_type, country). For custom properties stored in the JSON properties column, prefix with properties. (e.g., properties.plan, properties.amount).

​
Custom aggregations

Run sum, average, min, max, or count on numeric event properties: 
# Average order amount for purchase events
curl "https://your-tell-server/api/v1/metrics/events/custom?\
event=purchase&property=properties.amount&metric=avg&range=30d" \
  -H "Authorization: Bearer $TOKEN"

# Total revenue
curl "https://your-tell-server/api/v1/metrics/events/custom?\
event=purchase&property=properties.amount&metric=sum&range=30d" \
  -H "Authorization: Bearer $TOKEN"
Supported aggregation functions: sum, avg, min, max, count.

​
Drill-down

Inspect raw event data when you need to see individual records: 
curl "https://your-tell-server/api/v1/metrics/events/raw?range=7d&limit=50" \
  -H "Authorization: Bearer $TOKEN"
Returns rows with timestamp, event_name, device_id, and session_id. Add filter conditions to narrow down the results.

​
Breakdowns and comparison

Event metrics support the full filtering system — breakdowns by any field, period comparison, and all granularity levels. 
# Event count by device type, compared to previous period
tell metrics events --range 30d --breakdown device_type --compare previous