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

# Predictive activation schedules: cadence-driven audience refresh

> How a saved per-model schedule re-materializes a predictive model's ranked population into fresh segments on a cadence — cadence semantics, cold-start behavior, quiet-hours interaction, and when scheduled activation is the wrong tool.

# Predictive activation schedules

The [CDP predictive models guide](/guides/cdp-predictive-models) 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](/guides/cdp-predictive-models#4-per-model-activation-schedule).

## 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.

| Stage                                                | What happens there                                                         | How the schedule relates                                                                          |
| ---------------------------------------------------- | -------------------------------------------------------------------------- | ------------------------------------------------------------------------------------------------- |
| Predictive models panel → activation schedule        | Re-materializes the ranked top-N into a fresh static segment on cadence    | This is the schedule's whole job                                                                  |
| Campaign / flow targeting                            | Sends or enrolls the members of a segment                                  | Runs independently; reads whichever segment you point it at                                       |
| Audience activation pipeline (external destinations) | Publishes a segment to an ad network or webhook sink on `schedule_minutes` | Upstream of the destination: the destination re-resolves membership of the segment you configured |

The cadence vocabulary is deliberately separate from the destination's.
`schedule_minutes` on an
[audience activation pipeline](/guides/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](/guides/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](/guides/audience-export-adhoc) 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](/guides/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

* [CDP predictive models guide](/guides/cdp-predictive-models) — the catalog, the one-click activation, and the schedule API this page conceptualizes.
* [Audience activation pipelines](/guides/audience-activation-pipeline) — the downstream publish cadence (`schedule_minutes`) this page composes with.
* [Segment-triggered journeys](/guides/segment-triggered-journeys) — the per-event alternative to hourly snapshots.
* [How CDP segments recompute](/concepts/cdp-segment-recompute-model) — the real-time vs scheduled recompute model the sweep sits on.