> ## Documentation Index
> Fetch the complete documentation index at: https://docs.hightouch.com/llms.txt
> Use this file to discover all available pages before exploring further.

# Set up realtime audiences

> Realtime audiences evaluate user behavior during the current session using streaming events and warehouse context.

## Before you begin

* A configured [Customer Studio schema](https://docs.hightouch.com/customer-studio/schema.md)
* An event source sending events to Hightouch (Hightouch Events, Segment, RudderStack, or Snowplow)
* A destination that supports realtime syncing, or a system that will call the Membership API
* Realtime sync capability enabled for your workspace

## Overview

[Realtime audiences](https://docs.hightouch.com/real-time/overview.md) evaluate audience membership from live behavioral events during the current session, combining streaming events with warehouse attributes.

This guide walks you through the four steps to create one:

1. Connect an event stream
2. Define a **realtime event** in your schema
3. Build an audience that references that event
4. Configure how audience membership is delivered

## 1. Connect an event stream

Hightouch must receive realtime events before audiences can be evaluated.

Supported event sources include:

* Hightouch Events
* Snowplow
* RudderStack
* Segment

These events flow through Hightouch’s event pipeline and can be used for realtime audience evaluation once a corresponding **realtime event model** is defined in your schema.

See:

* [Set up Hightouch Events](https://docs.hightouch.com/events/event-streaming.md#set-up-event-streaming)
* [Migrate to Hightouch Events](https://docs.hightouch.com/events/migration-guide/overview.md)

## 2. Create a realtime event

Realtime events define which incoming events should be available for realtime audience evaluation.

To create one:

1. Go to **Customer Studio → Schema**

2. Locate or create a [**parent model**](https://docs.hightouch.com/customer-studio/schema.md#create-the-parent-model) (usually `Users`)

3. Click the **plus (+)** icon next to the parent model

   ![Create event](https://mintcdn.com/hightouch-3c037897/L_vQfA0JQEpeGUUo/images/real-time/setup/rta-schema-realtime-event.png?fit=max\&auto=format\&n=L_vQfA0JQEpeGUUo\&q=85\&s=4bf76fbe12099511584ae081e8a5d567)

4. Select **Create a related realtime event**

### Configure the event source

In the **Select event source** screen:

* Choose the **event source** (for example Segment or Hightouch Events)
* Enter the **event type** (for example `track`, `page`, or `order_completed`)
* Define event properties by adding columns and optional aliases
* Select the **timestamp column**, which determines when the event occurred

Click **Continue**.

![Event model](https://mintcdn.com/hightouch-3c037897/L_vQfA0JQEpeGUUo/images/real-time/setup/rta-new-event.png?fit=max\&auto=format\&n=L_vQfA0JQEpeGUUo\&q=85\&s=c340be909c3923caa615f30ec7c72688)

### Configure the event model

Next, configure how the event relates to your schema.

Provide:

| Field | Description |
| - | - |
| **Name** | Display name for the event in Customer Studio |
| **Description** | Optional explanation of the event |
| **Timestamp column** | Used for time-based audience filters |
| **Foreign key** | Column linking the event to the parent model (for example `user_id`) |

Click **Create realtime event**.

![Realtime event configuration](https://mintcdn.com/hightouch-3c037897/L_vQfA0JQEpeGUUo/images/real-time/setup/rta-configure-event.png?fit=max\&auto=format\&n=L_vQfA0JQEpeGUUo\&q=85\&s=9f990b30f3cef091c80f833e34145078)

> [!NOTE]
>
> Once created, the realtime event appears as an event filter option in the
> audience builder.

## 3. Create an audience

Next, create an audience that references the realtime event.

1. Go to **Customer Studio → [Audiences](https://app.hightouch.com/audiences?from=docs)**

2. Create a new audience or open an existing one.

3. Select the **parent model** connected to your realtime event.

> [!NOTE]
>
> Any existing audience can become a realtime audience once it includes a
> realtime event condition.

## 4. Add a realtime event condition

Add a filter that evaluates the realtime event.

1. In the audience builder, click **Add filter**

2. Select **Event** and choose your realtime event model

   ![Event filter](https://mintcdn.com/hightouch-3c037897/L_vQfA0JQEpeGUUo/images/real-time/setup/rta-event-filter.png?fit=max\&auto=format\&n=L_vQfA0JQEpeGUUo\&q=85\&s=f99f7cf14058af5c5ccfbb6a75e45fbb)

3. Define the event condition—for example, set it to "performed within the last 5 minutes" to capture recent activity

   ![Event performed](https://mintcdn.com/hightouch-3c037897/L_vQfA0JQEpeGUUo/images/real-time/setup/rta-event-performed.png?fit=max\&auto=format\&n=L_vQfA0JQEpeGUUo\&q=85\&s=5ada4da2be6d794f63089b28e310fe7f)

4. Click **Continue**

5. Finalize audience settings and click **Finish**

> [!NOTE]
>
> Time-based conditions expire automatically. When a user no longer meets a
> lookback-window condition—for example, "viewed a page 3 times in the last 4
> hours"—Hightouch removes them from the audience even if they generate no
> further events. This produces an audience exit, which is sent downstream if
> [exit events](#configure-events) are enabled on the sync.

## 5. Choose a delivery method

Realtime audiences can deliver membership updates through two mechanisms.

| Method | Best for | Description |
| - | - | - |
| **Realtime syncs** | Campaign tools, CRMs, advertising platforms | Push audience entry or exit events to supported destinations |
| **Membership API** | Websites, apps, personalization engines | Query audience membership on demand |

![API push](https://mintcdn.com/hightouch-3c037897/L_vQfA0JQEpeGUUo/images/real-time/setup/rta-api-push.png?fit=max\&auto=format\&n=L_vQfA0JQEpeGUUo\&q=85\&s=ab0130c79e75e9ada4c5829687788f0d)

### Option 1: Realtime syncs

Realtime syncs send audience membership changes to supported destinations.

When a user enters or exits an audience, Hightouch forwards a membership event to the destination.

Example event:
`User 123 entered audience "High-intent pricing visitors"`

#### Create a realtime sync

1. Open your audience and go to the **Syncs** tab

2. Click **Add Sync**

3. Select a destination that **supports realtime syncing**

   Supported destinations include:

   * [Braze](https://docs.hightouch.com/destinations/braze.md)
   * [Iterable](https://docs.hightouch.com/destinations/iterable.md)
   * [Meta Custom Audiences](https://docs.hightouch.com/destinations/facebook.md)
   * [Google Ads Customer Match](https://docs.hightouch.com/destinations/google.md)
   * [Segment](https://docs.hightouch.com/destinations/segment.md)
   * [Amplitude](https://docs.hightouch.com/destinations/amplitude.md)
   * [Webhooks](https://docs.hightouch.com/destinations/http-request.md)

   ![Supports realtime syncing](https://mintcdn.com/hightouch-3c037897/L_vQfA0JQEpeGUUo/images/real-time/setup/rta-supports-realtime-syncing.png?fit=max\&auto=format\&n=L_vQfA0JQEpeGUUo\&q=85\&s=0875fb1d3cd1eb08600e7353f5684bb1)

4. Complete the sync setup.

#### Configure events

After your sync has been created, open its **Configuration** tab to choose which membership changes to forward to the destination.

Depending on the destination, you can configure:

* **Entry events** — sent when a user qualifies for the audience
* **Exit events** — sent when a user leaves the audience
* **Custom event mappings** — additional event or property mappings supported by the destination

  ![Configure events](https://mintcdn.com/hightouch-3c037897/L_vQfA0JQEpeGUUo/images/real-time/setup/rta-configure-events.png?fit=max\&auto=format\&n=L_vQfA0JQEpeGUUo\&q=85\&s=e2f070fe875c073c17171e8cedbfbc94)

Send entry events when downstream systems only need to react when a user qualifies. Add exit events when downstream systems also need to react when a user stops qualifying—for example, to remove a suppression, cancel a journey, or stop targeting. Exit events fire whenever a user leaves the audience, including when a time-based condition ages out, not only when their latest event activity stops matching.

### Option 2: Membership API

The **Membership API** allows applications to check audience membership directly.

Your application sends a `user_id` and receives all realtime audiences the user currently qualifies for.

This is commonly used for:

* website personalization
* feature gating
* experimentation platforms
* in-app messaging

**Example request:**

```bash theme={null}
GET /v1/audiences/{parent_model_id}/{user_id}
Authorization: Bearer <API_KEY>
```

**Example response:**

```json theme={null}
{
  "parent_model_id": "1234567",
  "user_id": "123xyz",
  "audience_ids": ["1212121", "3434343"]
}
```

> [!NOTE]
>
> The Membership API returns realtime audience membership. To retrieve
> warehouse-backed traits and profile attributes, use the [Personalization
> API](https://docs.hightouch.com/real-time/personalization-api.md).

## Refresh warehouse-backed conditions

If a realtime audience includes warehouse-backed conditions, Hightouch evaluates those conditions against a cached copy of your warehouse data rather than querying the warehouse for every incoming event. That cache refreshes on a schedule, and you can see its freshness and control when it refreshes from the audience.

When an audience has warehouse-backed conditions, a freshness indicator appears in the audience header next to the source, showing the current state—**Current**, **Stale**, **Refreshing**, or **Pending**. Hovering over it opens a panel with the **Last pull** time and result, the **Next scheduled pull**, and a link to the pull history.

![Realtime audience warehouse cache freshness](https://mintcdn.com/hightouch-3c037897/L_vQfA0JQEpeGUUo/images/real-time/setup/rta-warehouse-freshness.png?fit=max\&auto=format\&n=L_vQfA0JQEpeGUUo\&q=85\&s=5790378cc30fc2029f0bbffd381a20be)

To control refreshes:

* **Run an on-demand pull.** On the **History** tab, select **Run \[source] pull** (labeled with your source, for example **Run Snowflake pull**) to refresh the cache immediately—useful when you've changed warehouse data or audience logic and want it reflected sooner than the next scheduled pull.
* **Adjust the refresh cadence.** Open the **Configuration** tab and set the **Pull schedule**. Options are every 4, 6, 8, 12, or 24 hours (the default is every 24 hours).
* **Review pull history.** The **History** tab lists recent pulls with their **Pull Date**, **Status**, **Trigger** (on-demand or scheduled), **Duration**, and **Rows**, so you can confirm refreshes are succeeding.

![Realtime audience warehouse pull history](https://mintcdn.com/hightouch-3c037897/L_vQfA0JQEpeGUUo/images/real-time/setup/rta-warehouse-pull-history.png?fit=max\&auto=format\&n=L_vQfA0JQEpeGUUo\&q=85\&s=630c6a0ae6d7627221e42a5bbae695bb)

![Realtime audience warehouse pull schedule](https://mintcdn.com/hightouch-3c037897/L_vQfA0JQEpeGUUo/images/real-time/setup/rta-warehouse-pull-schedule.png?fit=max\&auto=format\&n=L_vQfA0JQEpeGUUo\&q=85\&s=6306491ba9238991975edf15ad3cb2e5)

Scheduled pulls are always full refreshes. On-demand pulls may be partial when the staging table is still compatible.

> [!NOTE]
>
> Running an on-demand pull and changing the pull schedule require permission to
> update the audience.

Realtime event conditions are always evaluated live and are not affected by the warehouse refresh cadence.

## Example: Suppression use case

**Goal:** Hide a promotional banner after a user completes a purchase.

**Audience filters:**

* Event: `order_completed` in the last 5 minutes
* Trait: `LTV > 300`
* Property: `channel = web`

**Delivery:**
Realtime webhook sync to the personalization system

**Result:**
A user completes a purchase and immediately exits the promotional audience. The banner no longer appears during the same session.

> [!TIP]
>
> This pattern is commonly used for cart abandonment suppression, real-time
> promotions, and session-based personalization.

## Constraints

Keep the following limitations in mind when designing realtime audiences:

* Realtime event conditions **must include a lookback window** (maximum **24 hours**)
* Only event **count** conditions are supported today (no arbitrary aggregations like SUM)
* User property conditions from `identify` calls must go through the warehouse and cannot be evaluated in realtime

For the full list of constraints, see Constraints and limitations in the architecture guide.

## Best practices

When designing realtime audiences:

* Focus on **recent session behavior** (minutes rather than hours)
* Keep event conditions **specific and narrow**
* Combine live events with **warehouse traits** for richer targeting
* Monitor delivery through **sync logs** or **API responses**

Realtime event conditions must include a lookback window and support windows up to **24 hours**.

## Next steps

* [Real-Time Personalization overview](https://docs.hightouch.com/real-time/overview.md)
* Realtime audience architecture
* [Personalization API](https://docs.hightouch.com/real-time/personalization-api.md)