Documentation Index
Fetch the complete documentation index at: https://docs.tell.rs/llms.txt
Use this file to discover all available pages before exploring further.
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:
| Range | Meaning |
|---|
7d | Last 7 days |
30d | Last 30 days |
90d | Last 90 days |
3m, 6m, 12m | Last 3, 6, or 12 calendar months |
1h, 24h | Last 1 or 24 hours |
| Range | Meaning |
|---|
today | Today |
yesterday | Yesterday |
wtd | Week to date |
mtd | Month to date |
qtd | Quarter to date |
ytd | Year to date |
last_week | Previous complete week |
last_month | Previous complete month |
last_quarter | Previous complete quarter |
last_year | Previous complete year |
all_time | All available data |
Granularity
Control how data is bucketed in time. The default is daily.
| Granularity | Aliases |
|---|
minute | min, 1m |
hourly | hour, 1h |
daily | day, 1d |
weekly | week, 1w |
monthly | month |
quarterly | quarter |
yearly | year, 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
Filter conditions
Add conditions to narrow down which data is included. Each condition has a field, operator, and value.
Operators
| Operator | Aliases | Description |
|---|
eq | =, == | Equal |
ne | !=, <> | Not equal |
gt | > | Greater than |
gte | >= | Greater than or equal |
lt | < | Less than |
lte | <= | Less than or equal |
contains | like | Contains substring |
not_contains | not_like | Does not contain substring |
starts_with | | Starts with |
ends_with | | Ends with |
in | | In list of values |
not_in | | Not in list |
is_set | isset | Field is not null |
is_not_set | isnotset | Field is null |
regex | ~ | Regex match |
# 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
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
device_type — desktop, mobile, tabletcountry — country codeoperating_system — OS nameevent_name — event typelevel — log level (for log metrics)source — data source- Any
properties.* field
Comparison
Compare the current period to a previous one:
| Mode | Aliases | Compares to |
|---|
previous | prev, previous_period | Same duration, immediately before |
previous_year | yoy, year_over_year | Same 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
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"
Audience filtering
Scope any metric to a saved audience. Audiences are reusable user groups defined by property filters and behavioral rules — “US users who purchased in the last 30 days”, for example.
When an audience is applied, Tell resolves the rules to a set of matching device IDs and restricts the metric query to those users. This works across all metric types: active users, events, funnels, retention, lifecycle, and stickiness.
