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

# Filtering & Breakdowns

> Apply conditions with 15 operators, break down by any field, compare periods, and control time granularity.

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               |

**Predefined periods:**

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

**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`.

| Granularity | Aliases      |
| ----------- | ------------ |
| `minute`    | `min`, `1m`  |
| `hourly`    | `hour`, `1h` |
| `daily`     | `day`, `1d`  |
| `weekly`    | `week`, `1w` |
| `monthly`   | `month`      |
| `quarterly` | `quarter`    |
| `yearly`    | `year`, `1y` |

```bash theme={null}
# 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

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

### API format

Pass conditions as query parameters:

```bash theme={null}
# 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:

```bash theme={null}
# 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:

| Mode            | Aliases                   | Compares to                       |
| --------------- | ------------------------- | --------------------------------- |
| `previous`      | `prev`, `previous_period` | Same duration, immediately before |
| `previous_year` | `yoy`, `year_over_year`   | Same dates, one year earlier      |

```bash theme={null}
# 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:

```bash theme={null}
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](/analytics/audiences). 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](/analytics/funnels), retention, lifecycle, and stickiness.