Predictive traits


Audience	Marketers and analytics/data engineers
Prerequisites	A defined schema with at least one parent model (for example, `Users`). Event data that reflects the outcome you want to predict (for example, purchases, cart completions). (Optional) Connected destinations for syncing audiences.

Overview

When defining audiences, you sometimes want to act on signals about what customers are likely to do next, not just what they have already done.

Predictive traits extend Customer Studio traits with AI-powered scores that estimate the likelihood of a user performing a future action.

For example:

Purchase propensity: probability that a user will make a purchase within the next 7 days
Cart completion propensity: probability that a user who started checkout will complete their purchase
Churn prediction: probability that a user will not perform a key event (such as a purchase or login) within a given timeframe

Predictive traits are refreshed automatically on a schedule so your campaigns always use the latest predictions.

The predictive traits suite also includes catalog recommendations for personalized item-level recommendations and lookalike audiences for finding users similar to your best segments.

Predictive traits are built on the same machine learning models used in Hightouch AI Decisioning. They are automatically trained on your historical event data and do not require custom ML expertise.

Configure predictive inputs

Before you create a predictive trait, you must define predictive inputs in your schema. Predictive inputs are the user properties and event data that models use for training and scoring.

To configure predictive inputs:

Go to Customer Studio → Schema.
Select your parent model (for example, Users).
Open the Predictive Inputs tab.
Under User Properties, select the columns from this model that can help identify patterns — for example, age, country, device, plan_tier.
Under Key Events, add the event models that are relevant to the prediction target. Events must have a primary key configured to be available for selection.

Predictive Inputs tab on a parent model showing user properties and key events configuration

Once saved, these inputs are reusable across multiple predictive traits, catalog recommendations, and lookalike audiences.

Create a predictive trait

To create a predictive trait:

Go to Customer Studio → Traits.
Click Create → New trait.
In the Method step, select a parent model (for example, Users).
Under Calculation method, select Prediction.
Click Continue.

Method step showing parent model selection and Prediction calculation method

In the Calculation step, configure the prediction settings. The remaining settings on this page are optional.

Calculation step showing event selection, timeframe, eligible users, and update schedule

Under What action do you want to predict?, select the event to forecast (for example, Purchases). Only events with primary keys that are configured as predictive inputs are shown.

Event selection showing "What action do you want to predict?" with Purchases selected

Under What kind of prediction is this?, set the prediction timeframe — for example, "Event Performed within the next 7 Day(s)." Optionally, enable This is a churn predictor to score users based on the likelihood of not performing the event within the timeframe.

Timeframe configuration showing prediction window and churn predictor toggle

(Optional) Under Who should this prediction apply to?, add filters to restrict which users are scored — for example, based on something they've already done, like signing up or viewing a page.

Under How often should scores be updated?, set the refresh cadence. More frequent updates keep scores fresh but use more warehouse resources.

Click Continue.

In the Finalize step, name your trait, optionally add a description, review the calculation summary, and click Create trait.

Finalize step showing trait name, description, training notice, and calculation summary

The system trains a model using your data and generates predicted scores for each user. Training typically takes several hours but will vary based on warehouse size and the amount of data being processed.

View and use predictive traits

After training completes, predictive traits appear in the Traits list with type Predictive.

You can:

Preview results in the trait details page
Use in audiences by filtering on score thresholds or percentile ranges
Sync predictions to destinations such as ad platforms, ESPs, or CRMs for activation

Analyze predictions

After the model finishes training, the Prediction analysis tab on the trait detail page displays performance metrics. The page shows the total number of users scored and the last run date. Below these stats, you can explore results at different score thresholds.

Percentile buckets

The analysis page shows preset score buckets — Top 20%, Bottom 80%, Top 50%, and a Custom option. Each bucket displays the number of users in that tier and their conversion rate. Use these to gauge how concentrated predictive value is at the top of the distribution and to choose effective thresholds for targeting.

Model metrics

The analysis page displays three model performance metrics:

AUC (Area Under the Curve) — Measures how well the model separates users who will perform the predicted action from those who won't. Values closer to 100% indicate stronger separation.
Log Loss — Measures how confident and accurate the model's predictions are. Lower values are better — they mean the model's probability estimates closely match reality.
Average Precision — Measures the quality of the model across all confidence thresholds. A higher value means the model maintains good precision across a range of recall levels.

Top Feature Importance

The analysis page also lists the features that contribute most to the model's predictions, ranked by their share of total importance. This helps you understand which user properties and events drive the model's scoring.

Use percentile thresholds to build high-value segments. For example, create an audience of “Top 20% purchase propensity” users and sync them to ad channels for efficient spend.

Use predictive traits in audiences

You can use predictive traits when defining audiences the same way you use other traits.

Go to Customer Studio → Audiences and click Add audience.
In the audience definition, select a trait.
Set the score range or percentile range you want to include (for example, 80–100%).
(Optional) Combine the predictive filter with other attributes, such as country = US or plan_type = paid.

Predictive traits can be layered with demographic or behavioral conditions, giving you highly targeted segments. For example:

High propensity to purchase + specific geography (US, Canada)
Cart completion propensity + recent site activity (visited in the last 7 days)

Predictive traits update on a schedule. Between updates, some people may complete the action you’re predicting (like making a purchase) but their score won’t change until the next update. To keep your audience focused on people who haven’t yet acted, add a filter to exclude people who have already performed the predicted event (e.g, Purchases = 0 or Purchases (in last 7 days) = 0). This helps make sure your campaign only includes users who are still likely to take action.

Sync predictive audiences

Once you define an audience with predictive traits, you can sync it to any connected destination the same way you sync other audiences.

For example, you might sync:

High purchase propensity users to Google Ads or Meta Ads for paid acquisition
High cart completion propensity users to an ESP for checkout reminder emails

When syncing, predictive scores are included alongside user attributes so downstream tools can use them directly.

Sync configuration with predictive scores

After syncs run, you can monitor performance and health in the Syncs > Overview tab.

You don’t need to configure anything special for predictive traits when syncing--they behave like any other trait and can be mapped directly to destination fields.

Troubleshooting

If a predictive trait run fails, Hightouch assigns an error code that identifies the cause. The table below covers all predictive trait error codes. For a complete reference of all Hightouch error codes, see Error codes.

Error code	What it means	How to resolve
`NO_USERS_IN_INPUT_FILE`	The training audience returned no users.	Check that the parent audience or model query returns rows before training starts.
`NO_USER_ROWS_AFTER_FILTERS`	Users were present initially, but predictive filters removed all of them.	Loosen the filters or verify that event and property conditions match real data.
`NO_TRAINING_DATA_FILES`	Hightouch couldn't generate the training dataset.	Confirm that the configured events return data and the event model is queryable.
`LABEL_FREQUENCY_TOO_LOW`	There aren't enough examples of the target outcome to train the model reliably.	Increase the lookback window, reduce filters, or choose a higher-volume outcome event.
`NO_POSITIVE_EXAMPLES`	The training data contains zero positive examples of the target event.	Check that the outcome event is occurring for users in scope.
`TRAINING_MATRIX_DOWNLOAD_FAILED`	An internal failure occurred while retrieving the training artifact.	Retry the run. If it persists, — this is typically not customer-fixable.
`NO_KEY_EVENTS`	No feature-generation events are configured.	Add at least one event input in the predictive trait configuration before retraining.
`EVENT_MODEL_MISCONFIGURED`	The event model configuration is invalid.	Confirm the event model exists, has a valid primary key, and includes all referenced columns.
`EVENT_QUERY_FAILED`	Hightouch couldn't query event data from the warehouse.	Check warehouse permissions, model SQL, and whether the referenced tables still exist.
`SOURCE_ACCOUNT_LOCKED`	The warehouse user account is locked.	Wait for the lockout to clear, or have your warehouse admin re-enable the account.
`UNKNOWN_EVENT_IN_FILTER`	A predictive filter references an event Hightouch can't resolve.	Check for renamed, deleted, or misconfigured events in the predictive trait setup.
`INVALID_EVENT_PROPERTY_CONDITION`	An event-property filter is malformed.	Verify the filter syntax and confirm you're using valid string property names.
`NO_EVENT_DATA_FILES`	No event data was produced for training or inference.	Confirm the configured events have recent data and event pulls are succeeding.
`TRAINING_ERROR`	An internal training failure occurred.	Retry once. If it repeats, .
`CACHED_EVENT_PULL_DISABLED`	A required event pull is disabled.	Re-enable the event pull in your schema configuration and rerun the predictor.
`MALFORMED_EVENT_DATA`	Numeric event fields contain invalid values.	Clean the source data so numeric columns contain only valid numbers (no strings, nulls in numeric-only fields, etc.).
`MODEL_QUERY_FAILED`	Hightouch couldn't query the parent model data needed for the run.	Check that the parent model still exists and all referenced columns are present.