Skip to main content

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