Prediction models
Predicts a user's churn risk, or the likelihood that they will perform a specific event, from their past behavior. You use the scores in audiences and journeys.
Predicts a user's churn risk, or the likelihood that they will perform a specific event, from their past behavior. You use the scores in audiences and journeys.
Manage them from the Predictions page in the dashboard or through the API.
POST /v1/apps/{appId}/predictions
Authorization: Bearer <admin-scoped key>
{ "slug": "satin_alma", "name": "Purchase", "kind": "event", "event_names": ["purchase"], "horizon_days": 30 }| Field | Description |
|---|---|
kind | churn: producing no events at all within the horizon. event: producing the selected events |
event_names | Up to 10 events for the event type |
horizon_days | How far ahead the model looks, 7–90 days, default 30 |
slug | Short name used in audiences |
The model is retrained every day. POST /predictions/{id}/compute trains it immediately. You can set up at most 10 models per app.
How it works
The model takes a point in time one horizon in the past. It learns by comparing behavior before that point with what happened after it, then applies what it learned to today's behavior. Users with events in the past 90 days are covered. The signals are recent activity, event frequency, number of active days, target event history, user age, sends and engagement. Personal fields such as name and email do not go into the model, and no data is sent to an external service.
The method is logistic regression: you can see which signal has an effect, and in which direction.
Outcome (outcome)
| Value | Meaning |
|---|---|
ready | Scores were written |
insufficient_data | Fewer than 200 users, or fewer than 20 samples in one of the two outcomes. No scores are written |
low_quality | Performance (AUC) below 0.60. No scores are written, and old scores are deleted |
The metrics in the response contain the following: auc is the performance measured on users not used in training (0.5 is random, 1 is perfect). calibration shows the predicted and actual rate per bucket: if the two columns are close, you can trust the score. importance is the effect of each signal; it shows correlation, not causation.
Using the score
The score is a probability from 0 to 100. Buckets: low (0–39), medium (40–69), high (70–100).
{ "all": [{ "field": "prediction.satin_alma", "op": "gte", "value": 70 }] }Operators: eq, gt, gte, lt, lte, between. Users without a score do not match. User list: GET /predictions/{id}/users?bucket=high.
Limits
- A score is a probability, not a certainty. Do not use it on its own for decisions that have legal or similarly significant effects on a user; when processing personal data, consider with your legal counsel whether to mention profiling in your privacy notice.
- Anonymous users do not get scores.
- When a model is disabled, its scores are deleted. Audiences tied to a deleted model match no one.
Report builder
Build your own report for a question the built-in tabs don't answer: choose a source, metrics, up to two breakdowns and filters. Available on the Reports page in the dashboard or through the API. You can save the report, download it as CSV…
Event Streams: webhook body template and event filter
Event Streams lets you transform the body of outgoing webhooks (docs/webhooks.md) into the format the receiver expects and receive only the events you care about (ADR-0030). In the dashboard: Developer → Webhooks → endpoint…