Audiences

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

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:

{
  "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:

{
  "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:

{
  "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:

{
  "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:

curl https://your-tell-server/api/v1/audiences/aud_x7k9m2/count \
  -H "Authorization: Bearer $TOKEN" \
  -H "X-Workspace-ID: ws_abc123"

{
  "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 to scope any query — DAU, events, 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

curl https://your-tell-server/api/v1/audiences \
  -H "Authorization: Bearer $TOKEN" \
  -H "X-Workspace-ID: ws_abc123"

Returns the audiences in the workspace as a list response: one page in items (default 50, max 200) and the full count in total.

Get an audience

curl https://your-tell-server/api/v1/audiences/aud_x7k9m2 \
  -H "Authorization: Bearer $TOKEN" \
  -H "X-Workspace-ID: ws_abc123"

Update an audience

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

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 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 — the filter system that audiences plug into
Funnels — measure conversion for a specific audience
Segments — lifecycle-based user groups
Data queries API — full API reference for audience endpoints

Getting Started

Tracking

Pipeline

Analytics

Installing

Create an audience

Definition syntax

Property filters

Behavioral rules

Lookback window

Check member count

Use audiences in metrics

Manage audiences

List audiences

Get an audience

Update an audience

Delete an audience

Audiences vs segments

What’s next

​Create an audience

​Definition syntax

​Property filters

​Behavioral rules

​Lookback window

​Check member count

​Use audiences in metrics

​Manage audiences

​List audiences

​Get an audience

​Update an audience

​Delete an audience

​Audiences vs segments

​What’s next

Create an audience

Definition syntax

Property filters

Behavioral rules

Lookback window

Check member count

Use audiences in metrics

Manage audiences

List audiences

Get an audience

Update an audience

Delete an audience

Audiences vs segments

What’s next