Skip to main content
Every Tell metric supports the same filtering system. You can narrow results with conditions, split them by a dimension, change the time granularity, and compare against a previous period — all using the same parameters across the CLI, API, and TUI.

​
Time ranges

Tell supports relative ranges, predefined periods, and custom date ranges. Relative ranges — look back from today:
RangeMeaning
7dLast 7 days
30dLast 30 days
90dLast 90 days
3m, 6m, 12mLast 3, 6, or 12 calendar months
1h, 24hLast 1 or 24 hours
Predefined periods:
RangeMeaning
todayToday
yesterdayYesterday
wtdWeek to date
mtdMonth to date
qtdQuarter to date
ytdYear to date
last_weekPrevious complete week
last_monthPrevious complete month
last_quarterPrevious complete quarter
last_yearPrevious complete year
all_timeAll available data
Custom date range — comma-separated start and end: 
2024-01-01,2024-03-31

​
Granularity

Control how data is bucketed in time. The default is daily.
GranularityAliases
minutemin, 1m
hourlyhour, 1h
dailyday, 1d
weeklyweek, 1w
monthlymonth
quarterlyquarter
yearlyyear, 1y
# Hourly DAU for today
tell metrics dau --range today --granularity hourly

# Monthly event counts for the year
tell metrics events --range ytd --granularity monthly
Omit granularity to get a rolling window — a single aggregate value instead of a time series.

​
Filter conditions

Add conditions to narrow down which data is included. Each condition has a field, operator, and value.

​
Operators

OperatorAliasesDescription
eq=, ==Equal
ne!=, <>Not equal
gt>Greater than
gte>=Greater than or equal
lt<Less than
lte<=Less than or equal
containslikeContains substring
not_containsnot_likeDoes not contain substring
starts_withStarts with
ends_withEnds with
inIn list of values
not_inNot in list
is_setissetField is not null
is_not_setisnotsetField is null
regex~Regex match

​
API format

Pass conditions as query parameters: 
# Filter to mobile users in the US
curl "https://your-tell-server/api/v1/metrics/dau?range=30d\
&conditions[0][field]=device_type&conditions[0][operator]=eq&conditions[0][value]=mobile\
&conditions[1][field]=country&conditions[1][operator]=eq&conditions[1][value]=US" \
  -H "Authorization: Bearer $TOKEN"

​
JSON properties

Filter on custom event properties using dot notation. Properties stored in the JSON properties column are accessed as properties.field_name: 
conditions[0][field]=properties.plan&conditions[0][operator]=eq&conditions[0][value]=pro
Nested paths work too: properties.user.role.

​
Breakdowns

Add a breakdown to split any metric by a dimension: 
# DAU by country
tell metrics dau --range 30d --breakdown country

# Events by event name
tell metrics events --range 7d --breakdown event_name
The response returns data grouped by each dimension value. Common breakdown fields:
  • device_type — desktop, mobile, tablet
  • country — country code
  • operating_system — OS name
  • event_name — event type
  • level — log level (for log metrics)
  • source — data source
  • Any properties.* field

​
Comparison

Compare the current period to a previous one:
ModeAliasesCompares to
previousprev, previous_periodSame duration, immediately before
previous_yearyoy, year_over_yearSame dates, one year earlier
# This month vs last month
tell metrics dau --range 30d --compare previous

# Year-over-year MAU
tell metrics mau --range 90d --compare yoy
The response includes a comparison object with previous_total, change (absolute), percent_change, and optionally the previous period’s data points.

​
Limits

Results are capped at 10,000 rows by default. For raw drill-down queries, set limit explicitly: 
curl "https://your-tell-server/api/v1/metrics/events/raw?range=7d&limit=100" \
  -H "Authorization: Bearer $TOKEN"