--- title: "Audiences" description: "Build, manage, and activate audiences with the Lytics audience builder." url: "https://www.contentstack.com/docs/lytics/audiences" product: "Contentstack" doc_type: "guide" audience: - developers - admins version: "current" last_updated: "2026-11-05" --- # Audiences Build, manage, and activate audiences with the Lytics audience builder. ## Introduction Audiences are central to creating personalized marketing using Lytics. They group users who share characteristics so you can target them in campaigns, personalize experiences, export to downstream tools, and explore user behavior. Audiences stay up to date automatically — as users' behavior changes, they join or leave audiences in real time. Access the audience builder from the left navigation: **Audiences & Profiles → Audiences**, then click **\+ Create Audience**. ![Audiences index page](https://images.contentstack.io/v3/assets/blt2d43f51baca745a8/amd375ee3b08b42028/adca30c603b4a34631afdb4b/v2-audiences-index-v3.png) ## Creating a New Audience An audience consists of two parts: **details** (name, description, configuration) and a **definition** (the rules that decide who belongs). ### Audience Details The top of the builder collects metadata about the audience. ![Audience details — Name, Description, Groups, Slug, Expires After, Access](https://images.contentstack.io/v3/assets/blt2d43f51baca745a8/am9f73323f0fab17c7/88126920b9021c3721033ed1/56cc29f8fdb50490fc785e1bc830aa74c25b9e702ea2c51436b82f63e765ba1a-v2-details-section.png) Field Required Purpose **Name** Yes Human-readable name shown across the Lytics UI. **Description** No Optional longer explanation of what the audience targets. **Groups** No Assign to one or more groups for organization. Groups are managed from the Audiences list page. **Slug** No A unique, URL-friendly identifier used when referencing this audience via APIs or SDKs. If left blank, one is generated from the name. **Expires After** No Optional expiration date, blank by default. On this date a cleanup job deletes the audience definition — the profiles that matched it are not affected in any way. **Note:** if a downstream dependency (export, campaign, other audience) uses this audience, expiration will fail and the audience is kept. **Access: Enable for Personalization** No When on, the audience is surfaced by the [personalization API](/docs/developers/apis/lytics-api/v1/personalization#user-me) and available to Experiences, Pathfora, and tag-based personalization. Leave off for audiences used only in exports or internal reporting. **Audiences do not expire on their own** An audience is a live filter, not a stored snapshot of people. Membership is re-evaluated as profile data changes, so an audience defined years ago returns whoever matches _today_ — its age has no bearing on who is in it. Nothing expires unless someone sets **Expires After** on that specific audience. To check, open the audience in the builder and look at the field, or read expires\_at from the [segment API](/docs/developers/apis/lytics-api/segments#get-segment) — null means no expiration was ever set. Data lifecycle is controlled separately, on the data rather than on the audience definition. See [Schema Retention](/docs/lytics/schema-retention) for field- and table-level retention, [Profile Controls](/docs/lytics/profile-schema) for nightly profile culling, and [Privacy and Data Protection](/docs/lytics/privacy-and-data-protection) for data subject requests. **Expiration deletes the audience, not the people in it** **Expires After** removes the saved definition — the rule that describes who qualifies. It does not delete, suppress, or modify a single profile. Everyone who matched keeps their profile, fields, event history, and membership in every other audience; they simply stop being described by an audience that no longer exists. Expiring an audience is therefore not a data retention mechanism and does not satisfy any data minimization or deletion obligation. To act on profile data itself, use [Schema Retention](/docs/lytics/schema-retention), [profile culling](/docs/lytics/profile-schema#cull-user-filter), or [Identity Deletion](/docs/lytics/identity-deletion). **Naming tip** A Lytics account often ends up with dozens or hundreds of audiences. Use a consistent naming convention — a common prefix per campaign or category (e.g. Holiday Promo: Tech Lovers, Holiday Promo: Loyal Shoppers) keeps related audiences grouped together in the list and easier to find. Admins can also define structured name templates — with dropdowns, free-text fields, and fixed tokens — and optionally require every new audience to use one. See [Audience Naming Conventions](/docs/lytics/audience-naming-conventions). **Insights** [Lytics Insights](/docs/lytics/insights) are generated automatically for behavioral and engagement audiences. You can also nominate up to **10 custom audiences** to be prioritized as candidates for Insights — Lytics ranks candidates by statistical significance and how frequently the audience is used, so nomination doesn't guarantee inclusion. ### Defining Rules The **Definition** section is where you specify which users belong to the audience. Every audience has at least one **Rule set** containing one or more **rules**. Each rule is configured through the **Configure rule** panel, which offers these tabs: * **Attribute** — build rules based on user profile fields (the most common case). * **Audience** — reference another existing audience as a building block. * **Flow** — target users by where they are in a flow. On user audiences, for people with access to Flows. As you add and edit rules, the **This audience** panel on the right updates in real time with the current user count and percentage of total users. The **Sample Profiles** panel shows a preview of matched users. #### Attribute Rules The **Attribute** tab lets you build rules on any [user profile field](/docs/lytics/user-fields). ![Attribute tab with field list, next to the Audience and Flow tabs](https://images.contentstack.io/v3/assets/blt2d43f51baca745a8/am6a6b86e7a9fce860/0f4a188e57721257a8d7195d/v2-definition-attribute-tab.png) Filter the field list to find the right field: Filter What it does **Search for a Field** Text search against field names. **Source** Limit to fields from a specific data stream. **Coverage** Limit to fields populated on at least X% of profiles, so you don't build rules on sparsely-populated fields. Click a field to open its configuration, choose an operator and value, then click **Add rule**. Numeric fields show a histogram of value distributions and a table of sample values you can pick from. ![Configuring a numeric rule — Total Number of Visits, with operators and value distribution](https://images.contentstack.io/v3/assets/blt2d43f51baca745a8/amec507c5e28ef9f45/c6378b4ffa5c055627fd226d/1cd6b279e3323b2509449a3adedd61230476db0ce9b25a5b208786ffa16a7b04-v2-definition-numeric-config.png) Rules work differently depending on the field type — see [User Field Types](#user-field-types) below. #### Audience Rules The **Audience** tab lets you use an existing audience as a rule. ![Audience tab showing existing audience selector](https://images.contentstack.io/v3/assets/blt2d43f51baca745a8/am186337d8f6e86dbc/402b996a18fd468812426c3d/v2-definition-audience-tab-v3.png) Filter with: Filter What it does **Search for an Audience** Text search against audience names. **Audience Type** Limit by type (All, Behavioral, Characteristic, etc.). **Audience Group** Limit to audiences in a specific group. Select an audience to add it as a rule. #### Flow Rules The **Flow** tab builds a rule from where users are in a [flow](/docs/lytics/flows). It appears on user audiences for people with access to Flows. 1. Pick the flow and its version. 2. Pick a condition: **Currently At** (users at that stage right now) or **Has Reached** (users who reached it on their latest pass through the flow, even if they've moved on). 3. Pick one or more of the flow's stages by name. ![Flow tab — a flow, its version, the Has Reached condition, and a stage](https://images.contentstack.io/v3/assets/blt2d43f51baca745a8/amfbfc869e44b559e2/07fb223d5bce05d5769ee681/v2-definition-flow-tab.png) A saved Flow rule reads back as the flow and stage names wherever the audience builder shows it. **Content Affinity and Topics** Supertopics, Topics, and related interest signals appear in the **Attribute** tab alongside other user fields — search by the Supertopic or Topic name to find them. A finished rule reads lytics\_rollup.\`Supertopic name\` for a Supertopic and lytics\_content.\`Topic name\` for a Topic. See [Topics & Supertopics](/docs/lytics/topics-and-supertopics) and [Topics](/docs/lytics/topics) for how interest data is modeled. **Geolocation rules** Geolocation fields (country, region, city, radius-from-point) live in the **Attribute** tab. Search for _geo_ or the specific field name to find them. ### User Field Types How you configure a rule depends on the type of the user field. Expand the sections below for the supported operators and UI behavior of each type. Numeric User Fields ![Numeric field rule configuration](https://images.contentstack.io/v3/assets/blt2d43f51baca745a8/amec507c5e28ef9f45/c6378b4ffa5c055627fd226d/1cd6b279e3323b2509449a3adedd61230476db0ce9b25a5b208786ffa16a7b04-v2-definition-numeric-config.png) Numeric fields (e.g. _Total Number of Visits_, _Total Pageview Count_) support these operators: * **equals** — exact match * **is greater than** / **is at least** — minimum thresholds * **is less than** / **is at most** — maximum thresholds * **equals one of** — match any of a list * **exists** — include everyone with a value The **value distribution** bubble chart shows which values are most common across your user base; click a bubble or select from the **Selected/Value/User Count** table to pick a value. Use **View sample values** to inspect matching profiles before saving. Text User Fields ![Text field rule configuration](https://images.contentstack.io/v3/assets/blt2d43f51baca745a8/amf3a6e3ab310d635e/b6837e6b6890a12e52a3fa5f/5c2667d7c45f9986cb8829fbba341e2265b72bc74c4b2b9237dcc1791ac0c996-v2-definition-text-config.png) Text fields (e.g. _First Name_, _Last Visit City_) support these operators: * **equals** — exact match (case-sensitive) * **contains** — substring match anywhere in the value * **is like** — pattern match with \* as a wildcard (e.g. test\* matches "testing", \*test\* matches "my test case") * **equals one of** — match any of a list of values * **exists** — include everyone with a non-empty value Pick a value from the bubble chart or the sample values table, or type one into **This Value**. The bubble chart sizes values by user count. Date User Fields ![Date field rule configuration](https://images.contentstack.io/v3/assets/blt2d43f51baca745a8/amed1c96dffca79513/411e6a1391833db7f3f715b3/d63e4054163ddd6dc71d4d1d819d096e45363245497ae290b36a3df71b667e6d-v2-definition-date-config.png) Date fields (e.g. _Time of First Visit_, _Time of Last Visit_, _Created Timestamp_) support these operators: * **is after** — match values after a given date * **is before** — match values before a given date * **is between** — match values within a date range * **exists** — include everyone with a non-null date * **recurring anniversary** — match on the date's anniversary Pick **Relative Date** for windows that slide with "now" (e.g. visited in the last 7 days), or **Specific Date** for fixed points in time (e.g. created after 2024-01-01). Relative dates come with shortcuts for 1 day, 7 days, 30 days, 90 days, and 1 year in either direction (_in the past_ / _in the future_). **Recurring anniversary** builds an audience of people whose date comes around today, such as a birthday or a signup anniversary. Choose how it **Repeats**: **Yearly** (same month and day), **Monthly** (same day of the month), **Weekly** (same day of the week), or **Every N days**. **Days after date** is optional and moves the match later, for example 10 to reach people 10 days after their birthday. Matching uses today's date in UTC, so the audience updates daily. A date that doesn't exist in a period doesn't match: a Feb 29 birthday matches only in leap years, and the 31st only in months that have one. The operator is offered on date fields, but not on dates stored inside a map field. ![Recurring anniversary rule configuration — Created Timestamp repeating yearly, with an optional Days after date](https://images.contentstack.io/v3/assets/blt2d43f51baca745a8/amc16b9e3d9cdb2cd0/3d035f4f6d4d75a2c7242372/2e2bad7fb25a0a3cc06e4b46a0e7cfd8ff43c0c7517566411133f4ba1af2b36f-audiences-recurring-anniversary.png) Set User Fields ![Set field rule configuration](https://images.contentstack.io/v3/assets/blt2d43f51baca745a8/am68b677263369d675/336525644c49dd3130742aaf/5b7a50e7df62ef7ba1332479e4b12363b46a516b6e77c049270a2a4764bd0b9e-v2-definition-set-config.png) Set fields (e.g. _Web Domains Visited_, _All URL Paths Ever_, _Followed Sports_) collect multiple values per user over time. Operators: * **contains** — match users whose set contains the given value * **is like** — wildcard match with \* * **equals one of** — match users whose set contains any of a list of values * **exists** — include everyone who has any value in the set Tick values in the sample list to include them, or type into **These Values** to supply your own. The Set type: \[\]string pill at the bottom tells you the element type of the set. Map/Nested User Fields ![Map field — selecting a key](https://images.contentstack.io/v3/assets/blt2d43f51baca745a8/am05b5d11bedc29395/923c8361489d92d4c04dd702/8b64e1e7cf0784de4a3713fefb31cf7620a5ede8c1bfdf995f74fb9cabd14a29-v2-definition-map-config.png) Map fields (e.g. _Web Events By Hour_, _Events By Device_, _Signup Date for Event_) store values grouped by a **key**, giving you a two-step rule: 1. **Search for a key** — pick which slice of the map the rule operates on. For _Web Events By Hour_ the keys are hours (0–23); for _Events By Device_ the keys are device types; etc. 2. **Condition** — once a key is picked, the rule becomes a condition on the _value_ at that key, using the operators appropriate to the value type (numeric, string, date). The Map type: map\[string\]intsum pill at the bottom tells you the key type and value type. Use **Map Exists (No Key Needed)** to match users who have _any_ entry in the map, regardless of key. Use **Has Any of These Keys** to match users whose map has an entry for at least one of a list of keys — for example, anyone with an entry under either mobile or tablet in _Events By Device_. Type the keys, or pick them from the suggestions. ![Has Any of These Keys — entering a list of keys](https://images.contentstack.io/v3/assets/blt2d43f51baca745a8/am89afe201a411f38e/7d1a1fee64446a0905f62d93/762f7cec9c061365079a7cda7aad0a518b4222e8959def6dccf4ff75457f0971-audiences-map-has-any-keys.png) ### Combining Rules A **Rule set** groups one or more rules with a shared connector (AND or OR) and a shared Include/Exclude disposition. An audience can contain multiple rule sets, which are themselves combined with AND or OR — this lets you express precise logic like "(visitors from US AND engaged last 7 days) OR (known email AND abandoned cart)". #### AND: users must match every rule By default, additional rules are joined with **AND** — users must match all rules in the set. The connector toggle between rules shows "and" (grey). ![Two rules combined with AND](https://images.contentstack.io/v3/assets/blt2d43f51baca745a8/am1a647fa2e16af8e7/dcb9c92da704585740362f16/3c8b1a047827ba00adcf6196e2db90cc5ccfb0cbfd1e9c70feb03f591cdd8b2a-v2-definition-two-rules-and.png) #### OR: users must match at least one rule Click the connector toggle between rules to switch to **OR** — users match if they satisfy either rule. The audience size updates in real time. ![Two rules combined with OR](https://images.contentstack.io/v3/assets/blt2d43f51baca745a8/am93184b0495849f7e/7d14f9b4dd3b176376eb5239/9d8a74fc4c99c0331e9411c76d7d07a0e97783464d645a7efa43e809ce605905-v2-definition-two-rules-or.png) **The connector applies to the whole rule set — you can't mix AND and OR within a single set. To combine both, split into multiple rule sets.** #### Included / Excluded: invert a rule Each rule has an **Included / Excluded** toggle on its right side. When a rule is Excluded, users who _match_ the rule are kept _out_ of the audience. ![Rule toggled to Excluded](https://images.contentstack.io/v3/assets/blt2d43f51baca745a8/ame80c8d78a157f208/c9eb0a196036d3a55931e609/ab07653704d69176fbf6c8552bdfa8df472f896a3437fb2d5817d3d8a774723f-v2-definition-excluded.png) The same toggle exists at the rule-set level. Excluding a whole rule set removes everyone who matches it from the final audience. #### Adding another rule set Click **\+ Add rule set** below the existing set to start a new set. Rule sets are combined with AND or OR using the same connector pattern. Use rule sets to express logic that can't fit in a single flat list of rules. ### Saving the Audience Click **Save** at the bottom of the builder. Save is disabled until the audience has a Name and at least one valid rule in the Definition. After saving, you land on the audience's summary page. **Field-value limit** An audience can reference a maximum of **1,000 field values** across its definition. A "value" is a single evaluation against a user field, so the limit can be reached by: * One rule with 1001+ values in a multi-value operator (e.g. _equals one of_ with 1001 entries). * 1001+ separate single-value rules (e.g. each using _exists_). * Any mix in between, such as two rules with 500+ evaluations each. If you exceed the limit, saving fails with the error **"Audience too large! Remove values to save this audience."** Reduce the number of values or split the audience into smaller ones referenced via the **Audience** tab. * * * ## Managing Audiences The **Audiences** list page lets you browse, search, filter, group, edit, and delete audiences. ![Audiences list page](https://images.contentstack.io/v3/assets/blt2d43f51baca745a8/amd375ee3b08b42028/adca30c603b4a34631afdb4b/v2-audiences-index-v3.png) ### Browsing and Searching The list has a **Search** box that matches any part of an audience's name, slug, ID, tags, or description. It ignores case and spaces at either end. Wrap a term in double quotes ("sms") to match a whole value exactly. Search doesn't look inside an audience's definition, so a field name used in a rule won't find it. The list also has sortable columns for: Column What it shows **Name** Human-readable name with the slug rendered below in code style. **Size** Most recent user count (refreshed periodically — not real-time). **Last Modified** When the definition was last changed. **API** Whether the audience is exposed via the personalization API (the Access: Enable for Personalization toggle). **Managed** Lytics-managed prebuilt audiences are flagged here. **Download CSV** Trigger a CSV export of the audience's users. Click any column header to toggle sort. Pagination controls sit below the list; use **Show All** to disable pagination. ### Groups Groups organize audiences into logical buckets. The right-hand **Groups** panel lists built-in groups plus any custom groups you've created. ![Groups panel](https://images.contentstack.io/v3/assets/blt2d43f51baca745a8/am2344cee39b29ce03/1c01298d8037308878aa2aff/88d94664070658cad97bb47b616a588ee71faf2c26fef636d0a5ecade838c7a6-v2-groups-panel.png) Built-in groups Lytics computes automatically: * **All** — every audience in the account. * **Interest Audiences** — audiences built on content-affinity rules. * **Lookalike Audiences** — audiences generated from the Lookalike Models feature. * **My Audiences** — audiences you've created or edited recently. * **Recently Created** — audiences added in the last 7 days. * **Recently Updated** — audiences whose definitions changed in the last 7 days. * **Unused** — audiences not referenced by any export, campaign, or other audience. #### Creating a custom group Click the **+** next to **Groups** to create a custom group, give it a name, and save. #### Adding audiences to a group There are two ways to add audiences to a group: 1. **From the audience builder** — set the **Groups** field while creating or editing the audience. 2. **From the list** — select audiences via checkbox, click **Select an action**, and choose **Add to Groups**. Pick the target group(s) to apply. #### Editing or deleting a group Hover the group name in the **Groups** panel to reveal the **edit** (pencil) and **delete** (trash) icons. Deleting a group removes the group assignment from its audiences — it does not delete the audiences themselves. ### Audience Summary Click any row in the Audiences list to open the audience's summary page. It shows the audience name, ID, slug, created/updated dates, API access status, and the **Export / Edit / ⋯** actions. ![Audience summary page](https://images.contentstack.io/v3/assets/blt2d43f51baca745a8/am88ea92900835696a/88241ae126cfc9e44c5cf680/916ad308aa9f21b8d91002065967433410858b43c7a9e28c9fa0c9ce97e69aad-v2-audience-summary.png) Four tabs below the header give different views of the audience: * **Metrics** — headline user count and audience share, plus an activity graph of audience size over time, viewable at hourly, daily, weekly, or monthly intervals. Useful for spotting growth from a campaign or a sudden drop after a rule change. The graph begins to populate within a day of audience creation, and statistics start from the audience's creation date — there's no historical backfill for periods before the audience existed. To get an email when audience size goes out of expected bounds, set min/max thresholds on the activity chart — see [Metric Threshold Alerts](/docs/lytics/metric-thresholds). * **Details** — exports and jobs currently using this audience, plus a sample of recent users you can drill into. * **Characteristics** — a breakdown of who's in the audience by behavior, web activity, content affinity, and campaign interactions. Helpful for sanity-checking whether the rules are catching who you expected. * **Logs** — recent events on the audience. The **Source** control picks which kind you're looking at: _This audience_ is the audience's own history — creation, edits, and rule changes — while _Related activity_ is everything else that named it, such as an export job syncing it, with a **Source** column naming the job. **Load more** appends older entries a page at a time. ### Editing an Audience From the summary page, click **Edit** to reopen the audience in the builder. Make changes, then **Save**. Edits are picked up by downstream exports on the next refresh. **If the audience is referenced by an active triggered workflow, reconfigure the job after editing the audience so that the workflow picks up the new definition cleanly.** ### Duplicating an Audience From the summary page, click the **⋯** menu and choose **Duplicate**. You'll get a new audience with the same definition; adjust the name and rules as needed. ![Summary page options menu (Duplicate / Delete)](https://images.contentstack.io/v3/assets/blt2d43f51baca745a8/am385627335defddfa/f512fc2a8f8d62c389a154c2/f64287f3d30ddb1f0f403d8410c0c7d0a1240398691594a681c1194b4cf0bd7e-v2-audience-summary-menu.png) **The duplicate inherits the original audience's name and slug with duplicate appended. Update both before saving — keeping a clean, unique slug avoids confusion in API calls and downstream exports.** ### Deleting an Audience **Deleting an audience removes the audience definition only — it does **not** delete the user profiles that were in it.** #### Deleting a single audience From the summary page of the audience you want to delete, open the **⋯** menu and choose **Delete**. You'll be asked to confirm. #### Deleting multiple audiences Tick the checkboxes on the rows you want to remove. A blue action bar appears at the bottom showing the selection count. ![Audiences list with two audiences selected](https://images.contentstack.io/v3/assets/blt2d43f51baca745a8/am6bb9d76c56e751e1/18f02726006e0b4727e5c829/b8045988bb0f7cb698188b49d0bd3aba686a3cd7924988bcb69a68edf715383d-v2-audiences-multiselect.png) Click **Select an action**, then **Delete Audiences**. You'll be asked to confirm, and Lytics will check for downstream dependencies before deleting. ![Batch action menu — Add to Groups / Remove from Groups / Delete Audiences](https://images.contentstack.io/v3/assets/blt2d43f51baca745a8/am10cca76c435c7402/d0498e6c014158ba72893813/a4d3786de771a0572046c04cc4d7df2a178a62e10ec867455262a17e24075dfd-v2-audiences-multiselect-menu.png) **If any of the selected audiences are used by an active export, campaign, or another audience, Lytics prompts you to choose between deleting the dependents as well or skipping the deletion.** **An audience that a widget targets can't be deleted, even if only a draft version of the widget uses it. The delete fails with Used by widget