Skip to main content

​
Predictive activation schedules

The CDP predictive models guide showed the one-click activation — score a model’s population, take the top-N, materialize them as a static segment. That answers “build this audience once.” A predictive activation schedule answers the follow-up: “keep this audience current without anyone coming back to click.” Save a per-model plan once — cadence, top-N, and the segment-name template — and a background sweep re-materializes the model’s ranked population into a fresh segment on that cadence from then on. This page defines what the loop automates, how cadence semantics work, what the model re-scores on each run, how the loop interacts with tenant-owned quiet hours, and when scheduled predictive activation is the wrong tool. The per-model API surface itself is documented under the per-model activation schedule section of the models guide.

​
Section 1 — What the schedule automates

The manual activate action has a drift problem once scoring itself becomes automatic. Nightly churn-risk scoring already runs on a scheduler, so a segment materialized by a past click freezes the ranked population it was built from — every day the ranking moves, and the segment does not. The only way to close that gap by hand was to return to Audience → Predictive models and click Activate again. A schedule closes it once. Each saved plan pins four things per model:
  • enabled — an explicit on/off; a disabled plan stays saved so the toggle state is deliberate, not forgotten.
  • cadence — hourly, daily, or weekly.
  • topN — how many of the model’s top-ranked profiles each run materializes (1–500).
  • nameTemplate — the human-readable segment name each run’s fresh segment carries, so successive runs are distinguishable in the segment list the operator named once.
Each due run executes the identical chain the one-click activation runs: re-fit the model, re-score the scoring population, rank it, and materialize the top-N as a new static segment. The sweep never edits a past segment — it produces the current run’s snapshot alongside the previous ones.

​
Section 2 — Where the schedule runs in the pipeline

A predictive activation schedule operates at exactly one stage of the audience pipeline: the segment-materialization stage. It is not a send schedule and it does not move audiences downstream by itself. The cadence vocabulary is deliberately separate from the destination’s. schedule_minutes on an audience activation pipeline controls how often a segment is published outward; the predictive activation cadence controls how often a fresh ranked segment is created. Compose the two when you want both — point an activation destination at the segment family the schedule produces and let each cadence govern its own stage — or run one without the other when you only need one stage automated. Because the cadence values are hourly / daily / weekly, think in those units, not in minutes. An hourly plan refreshes the ranked list at most once per hour; a weekly plan holds a snapshot for a week. There is no sub-hourly option — one refresh per hour is the fastest the loop is designed to run, so reactions that must happen per event belong on a segment-triggered journey instead.

​
Section 3 — What each run re-scores, and cold-start behavior

A run does not re-use yesterday’s scores. It re-fits and re-scores from the live tenant data on every due tick, across the same four model families the catalog defines:
  • churn_propensity — re-scored from each contact’s current feature vector (tenure, recency, message counts, 30-day event volume and variety).
  • conversion_intent — same feature set, ranked on conversion probability.
  • lifetime_value — the regression output re-predicted per contact, ranked by predicted value.
  • engagement_fatigue — the opt-out / disengagement probability, re-fit against the latest subscribed-vs-opted-out outcomes.
Scheduled runs therefore ride on engagement history as it accumulates: a contact who went quiet since the last run moves up the churn ranking on the next one, and the fresh segment reflects that without any operator action. Cold start. A model that cannot be fit yet — fewer than 50 labelled outcomes, or a single outcome class in the training data — is not an error and does not block the cadence. The due run is recorded as skipped: insufficient data, the schedule’s cadence cursor still advances, and the loop keeps ticking. When the first fit succeeds, the next due tick materializes normally — there is no backlog to clear and nothing to re-trigger by hand.

​
Section 4 — Interaction with quiet hours and the destination pipeline

The sweep itself is time-blind by design: it materializes segments and never dispatches a message, so your tenant-owned quiet-hours rules do not gate it and it never defers to a recipient’s local time. Quiet hours are enforced downstream, where a compliant channel send actually happens — a campaign or flow that targets the fresh segment holds or sends per-recipient exactly as it would for any other audience. Keeping the sweep time-blind is what keeps the segment current around the clock while the dispatch layer still honors every tenant-owned sending window. The same separation holds for the audience activation pipeline. That pipeline’s schedule_minutes controls the publish cadence of one segment to one destination; the predictive cadence controls how often a new ranked segment is born. A destination pointed at a scheduled model’s output re-reads membership on its own minutes-based cadence — set the segment’s auto_refresh so the destination never publishes a stale membership read.

​
Section 5 — When not to use predictive activation

Scheduled re-materialization is the right tool when the question is “who are the top-N right now, on a recurring basis.” It is the wrong tool in three common shapes:
  • One-shot blasts. If the audience is a single planned send — a product announcement, a seasonal campaign — a manual activation or an ad-hoc export is correct. A schedule that creates a new segment every hour for a one-off blast is noise.
  • Per-event reactions. If a message should fire when a contact enters a state — a cart abandoned, a form completed — use segment-triggered journeys. The fastest predictive cadence is hourly; a per-event trigger runs in near-real-time and needs no schedule at all.
  • Fixed drip sequences. A drip campaign advances per member from their own enrollment moment. Re-materializing the underlying top-N on a cadence does not move anyone through a drip — enroll the segment in the flow and let the flow’s own cadence drive.
The diagnostic is simple: if the value comes from the ranking being fresh, schedule it. If the value comes from a member’s own timeline, trigger or drip it instead.

​
Section 6 — Limits and semantics to plan against

  • Cadence floor: the fastest plan is hourly. The sweep ticks more often than that, but no plan can re-materialize more than once an hour — the cadence gate, not the tick, is the enforcement.
  • Per-run top-N bound: topN is bounded at 1–500 per run, the same bound one-click activation enforces. A scoring population beyond the top bound is ranked but not materialized.
  • Model keys are a closed registry: a schedule can only be saved for the four built-in model families. Custom slugs are rejected at save time.
  • Per-operator plans de-duplicate across the workspace: two operators on the same workspace who save the identical model + cadence + top-N + name plan produce one scheduled run per cadence — not one segment per operator — and every contributor’s cadence cursor advances together. A deliberately different cadence or top-N is a different plan and runs on its own.
  • New segment per run: the loop does not update a standing segment in place. Each run materializes a new static segment named from your template, attributing the snapshot to the run that produced it. Point downstream surfaces at the current run’s segment (or gate membership with auto-refresh filters) rather than treating the schedule as an in-place list mutation.

​
Cross-references