Data Queries

The query API powers Tell’s analytics. Use it to fetch active users, events, sessions, logs, and stickiness metrics — with breakdowns, comparisons, and raw drill-down. All endpoints require a JWT token and X-Workspace-ID header:

curl "https://your-tell-server/api/v1/metrics/dau?range=30d" \
  -H "Authorization: Bearer $TOKEN" \
  -H "X-Workspace-ID: ws_abc123"

Active users

Track daily, weekly, and monthly active users:

# Daily active users, last 30 days
curl "https://your-tell-server/api/v1/metrics/dau?range=30d"

# Weekly active users, broken down by country
curl "https://your-tell-server/api/v1/metrics/wau?range=90d&breakdown=country"

# Monthly active users, compared to previous period
curl "https://your-tell-server/api/v1/metrics/mau?range=30d&compare=previous"

Endpoint	Metric
`/metrics/dau`	Daily active users
`/metrics/wau`	Weekly active users
`/metrics/mau`	Monthly active users

Each endpoint also has a /raw variant (e.g. /metrics/dau/raw) that returns the underlying user-level data with pagination.

Events

# Event volume over time
curl "https://your-tell-server/api/v1/metrics/events?range=30d&granularity=daily"

# Top events by count
curl "https://your-tell-server/api/v1/metrics/events/top?range=7d"

# Break down an event by a property
curl "https://your-tell-server/api/v1/metrics/events/properties?event=purchase&property=plan&range=30d"

# Custom aggregation — total revenue
curl "https://your-tell-server/api/v1/metrics/events/custom?event=purchase&property=amount&metric=sum&range=30d"

Endpoint	What it returns
`/metrics/events`	Event count over time
`/metrics/events/top`	Most frequent events ranked by count
`/metrics/events/top/{name}/raw`	Raw data for a specific event
`/metrics/events/properties`	Property breakdown (requires `event` and `property` params)
`/metrics/events/custom`	Aggregation on a property — `sum`, `avg`, `min`, `max`, `count`
`/metrics/events/raw`	Raw event data

Sessions

# Session volume
curl "https://your-tell-server/api/v1/metrics/sessions?range=30d"

# Top sessions by device type
curl "https://your-tell-server/api/v1/metrics/sessions/top?range=30d&property=device_type"

# Unique sessions
curl "https://your-tell-server/api/v1/metrics/sessions/unique?range=30d"

Logs

# Log volume over time
curl "https://your-tell-server/api/v1/metrics/logs?range=7d"

# Top logs by level
curl "https://your-tell-server/api/v1/metrics/logs/top?range=7d"

# Filter by service and level
curl "https://your-tell-server/api/v1/metrics/logs/raw?service=api&level=error&range=7d"

Log-specific filters: service, level, source.

Users and stickiness

# User count over time
curl "https://your-tell-server/api/v1/metrics/users?range=30d"

# Daily stickiness (DAU/MAU ratio)
curl "https://your-tell-server/api/v1/metrics/stickiness/daily?range=30d"

# Weekly stickiness (WAU/MAU ratio)
curl "https://your-tell-server/api/v1/metrics/stickiness/weekly?range=30d"

Common parameters

Most metric endpoints share these query parameters:

Parameter	Default	Options
`range`	`30d`	`7d`, `30d`, `90d`, or custom: `2025-01-01,2025-01-31`
`granularity`	`daily`	`minute`, `hourly`, `daily`, `weekly`, `monthly`
`breakdown`	—	Any dimension: `country`, `platform`, `device_type`, `os`, etc.
`compare`	—	`previous` (previous period) or `yoy` (year-over-year)
`conditions[N][field]`	—	Filter conditions (see Filtering)

Raw endpoints add pagination:

Parameter	Default	Description
`limit`	`100`	Max rows returned
`offset`	`0`	Skip rows for pagination
`count_total`	`false`	Include total count (slower)

SQL queries

For full flexibility, execute SQL directly against your analytics data. Rate-limited to 30 requests per minute.

curl -X POST https://your-tell-server/api/v1/data/query \
  -H "Authorization: Bearer $TOKEN" \
  -H "X-Workspace-ID: ws_abc123" \
  -H "Content-Type: application/json" \
  -d '{"query": "SELECT event, count() as cnt FROM events_v1 GROUP BY event ORDER BY cnt DESC LIMIT 10"}'

Returns:

{
  "columns": [
    { "name": "event", "data_type": "String" },
    { "name": "cnt", "data_type": "UInt64" }
  ],
  "rows": [
    ["page_view", 48210],
    ["click", 12503]
  ],
  "row_count": 2,
  "execution_time_ms": 42
}

Only SELECT statements are allowed. Queries are automatically scoped to your workspace database. Max 10,000 rows per query (default 1,000).

Data exploration

Discover what data is available before writing queries:

# List available data sources
curl https://your-tell-server/api/v1/data/sources \
  -H "Authorization: Bearer $TOKEN" \
  -H "X-Workspace-ID: ws_abc123"

# Get fields for a source
curl https://your-tell-server/api/v1/data/sources/events/fields \
  -H "Authorization: Bearer $TOKEN" \
  -H "X-Workspace-ID: ws_abc123"

# Get distinct values for a field
curl "https://your-tell-server/api/v1/data/sources/events/values/country?limit=20" \
  -H "Authorization: Bearer $TOKEN" \
  -H "X-Workspace-ID: ws_abc123"

Available sources

Source	Table	Description
`events`	events_v1	Custom events and page views
`logs`	logs_v1	Structured logs
`context`	context_v1	Device and session context
`user_traits`	user_traits_v1	User properties set via `identify`
`users`	users_v1	Unique users
`user_devices`	user_devices	Device-to-user mappings

What’s next

Boards & Metrics — save and visualize query results
Sharing — share metrics and boards publicly
SQL Analytics — SQL query patterns and tips

API Reference

​Active users

​Events

​Sessions

​Logs

​Users and stickiness

​Common parameters

​SQL queries

​Data exploration

​Available sources

​What’s next