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

# Audiences

> Define reusable user groups based on properties and behavior, then apply them to any metric.

Audiences are saved user groups defined by rules. Combine property filters ("country is US") with behavioral rules ("did purchase in last 30 days") to create a group, then use it to scope any metric — DAU, funnels, retention, events, and more.

## Create an audience

```bash theme={null}
curl -X POST https://your-tell-server/api/v1/audiences \
  -H "Authorization: Bearer $TOKEN" \
  -H "X-Workspace-ID: ws_abc123" \
  -H "Content-Type: application/json" \
  -d '{
    "name": "US power buyers",
    "description": "US users who purchased in the last 30 days",
    "definition": {
      "filters": [
        { "field": "country", "operator": "eq", "value": "US" }
      ],
      "events": [
        { "event": "purchase", "days": 30 }
      ]
    }
  }'
```

Response:

```json theme={null}
{
  "data": {
    "id": "aud_x7k9m2",
    "workspace_id": "ws_abc123",
    "owner_id": "usr_abc",
    "name": "US power buyers",
    "description": "US users who purchased in the last 30 days",
    "definition": {
      "filters": [
        { "field": "country", "operator": "eq", "value": "US" }
      ],
      "events": [
        { "event": "purchase", "days": 30, "filters": [] }
      ]
    },
    "created_at": "2025-06-15T10:30:00Z",
    "updated_at": "2025-06-15T10:30:00Z"
  }
}
```

Tell resolves the audience rules into a set of matching device IDs and injects them as a filter into any metric query. All rules are AND-combined — users must match every filter and every behavioral rule.

## Definition syntax

An audience definition has three parts: property filters, behavioral event rules, and an optional lookback window.

### Property filters

Each filter matches a field against a value using an [operator](/analytics/filtering#operators):

```json theme={null}
{
  "filters": [
    { "field": "country", "operator": "eq", "value": "US" },
    { "field": "device_type", "operator": "in", "value": ["mobile", "tablet"] }
  ]
}
```

**Field prefixes:**

| Prefix        | Source                           | Example                                      |
| ------------- | -------------------------------- | -------------------------------------------- |
| *(none)*      | Event top-level fields           | `country`, `device_type`, `operating_system` |
| `properties.` | Custom event properties          | `properties.plan`, `properties.amount`       |
| `trait:`      | User traits (set via `identify`) | `trait:plan`, `trait:company`                |

Trait filters join through the `user_traits` and `user_devices` tables automatically.

### Behavioral rules

Each rule matches users who performed a specific event within a time window:

```json theme={null}
{
  "events": [
    {
      "event": "purchase",
      "days": 30,
      "filters": [
        { "field": "properties.amount", "operator": "gte", "value": "100" }
      ]
    }
  ]
}
```

This matches users who made a purchase of \$100 or more in the last 30 days. The `filters` array on each event rule is optional — omit it to match any occurrence of the event.

### Lookback window

Set `lookback_days` to limit how far back Tell scans when resolving property filters. This improves query performance on large datasets:

```json theme={null}
{
  "filters": [
    { "field": "country", "operator": "eq", "value": "US" }
  ],
  "events": [
    { "event": "purchase", "days": 30 }
  ],
  "lookback_days": 90
}
```

Behavioral rules always use their own `days` window. The `lookback_days` field only affects property filters.

## Check member count

See how many users match an audience:

```bash theme={null}
curl https://your-tell-server/api/v1/audiences/aud_x7k9m2/count \
  -H "Authorization: Bearer $TOKEN" \
  -H "X-Workspace-ID: ws_abc123"
```

```json theme={null}
{
  "data": {
    "audience_id": "aud_x7k9m2",
    "count": 3842
  }
}
```

## Use audiences in metrics

Audiences filter every metric type. Pass the audience definition as part of the [filter system](/analytics/filtering) to scope any query — DAU, events, [funnels](/analytics/funnels), retention, lifecycle, and more.

This is handled at the query engine level: Tell resolves the audience to a set of device IDs, then restricts all metric queries to those devices.

## Manage audiences

### List audiences

```bash theme={null}
curl https://your-tell-server/api/v1/audiences \
  -H "Authorization: Bearer $TOKEN" \
  -H "X-Workspace-ID: ws_abc123"
```

Returns all audiences in the workspace.

### Get an audience

```bash theme={null}
curl https://your-tell-server/api/v1/audiences/aud_x7k9m2 \
  -H "Authorization: Bearer $TOKEN" \
  -H "X-Workspace-ID: ws_abc123"
```

### Update an audience

```bash theme={null}
curl -X PUT https://your-tell-server/api/v1/audiences/aud_x7k9m2 \
  -H "Authorization: Bearer $TOKEN" \
  -H "X-Workspace-ID: ws_abc123" \
  -H "Content-Type: application/json" \
  -d '{
    "name": "US power buyers (updated)",
    "definition": {
      "filters": [
        { "field": "country", "operator": "in", "value": ["US", "CA"] }
      ],
      "events": [
        { "event": "purchase", "days": 30 }
      ]
    }
  }'
```

Only the audience owner or a workspace admin can update an audience. All fields are optional — omit a field to keep its current value.

### Delete an audience

```bash theme={null}
curl -X DELETE https://your-tell-server/api/v1/audiences/aud_x7k9m2 \
  -H "Authorization: Bearer $TOKEN" \
  -H "X-Workspace-ID: ws_abc123"
```

Only the audience owner or a workspace admin can delete an audience.

## Audiences vs segments

[Segments](/analytics/segments) are lifecycle-based groups (new, returning, dormant, churned) computed automatically by Tell. Audiences are rule-based groups you define explicitly. Use segments for lifecycle analysis. Use audiences to target specific user populations across any metric.

## What's next

* [Filtering](/analytics/filtering) — the filter system that audiences plug into
* [Funnels](/analytics/funnels) — measure conversion for a specific audience
* [Segments](/analytics/segments) — lifecycle-based user groups
* [Data queries API](/api/queries) — full API reference for audience endpoints