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: Predefined periods: Custom date range — comma-separated start and end:

​
Granularity

Control how data is bucketed in time. The default is daily.
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

​
API format

Pass conditions as query parameters:

​
JSON properties

Filter on custom event properties using dot notation. Properties stored in the JSON properties column are accessed as properties.field_name:
Nested paths work too: properties.user.role.

​
Breakdowns

Add a breakdown to split any metric by a dimension:
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:
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:

​
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.