Skip to main content
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: 
{
  "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: 
{
  "filters": [
    { "field": "country", "operator": "eq", "value": "US" },
    { "field": "device_type", "operator": "in", "value": ["mobile", "tablet"] }
  ]
}
Field prefixes:
PrefixSourceExample
(none)Event top-level fieldscountry, device_type, operating_system
properties.Custom event propertiesproperties.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"

{
  "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 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 all audiences in the workspace.

​
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