Skip to content

Cold Start and Model Warm-Up

Last updatedView as Markdown

Arc XP Compass learns from two things: your content catalog and how your readers interact with it. When either is thin, such as a reader with no history, a story published a minute ago, or a model that was provisioned yesterday, Compass is in cold start. This page explains how personalization works, what Compass does while it is cold, and why the work you do before launch decides what readers see on day one.

How Compass personalizes

The Recommendations API applies several layers to produce a ranked list for each reader:

  • Model personalization. The recommendation model learns from your audience’s behavior (page views, clicks, engagement) and from your content metadata (categories, tags, authors, recency). Each reader receives a uniquely ranked set of results based on their interaction history.
  • Site partitioning. Every request is scoped to one site_id, so content published to one site does not appear in another site’s recommendations. See Site ID.
  • Filters. A request can be narrowed to an editorial section, a content type, or both. Filtering happens before ranking, so non-matching items are never scored and never compete for a slot, which is more efficient than excluding them in client code. See Compass API filters.

Personalization depends on accumulated history. Each of these layers works from the first request, but the first one improves only as interactions build up for a reader and for an item.

New readers and new content

The Recommendations API handles two cold-start scenarios automatically:

  • New or anonymous readers. When a reader has no interaction history, Compass returns popularity-based recommendations drawn from your content catalog. Results reflect what is trending among your broader audience, weighted by recency and content metadata. As the reader accumulates interactions, recommendations progressively become more personalized. This only works if the reader’s user_id stays stable, so the history has somewhere to accumulate. See User ID.
  • New content. Freshly published content with no engagement data is still eligible for recommendations. The model uses content metadata (categories, tags, author, recency) to place new items in front of relevant audiences immediately, which is why sparse metadata hurts new content most.

No special handling is required on your part for either scenario. The response shape is identical whether results are fully personalized or cold-started.

Before the model is trained

A newly provisioned tenant is cold in a broader sense: there may be no catalog, or a catalog but no trained model. What the recommendations endpoint returns in that period is decided by your tenant’s lifecycle status together with whether your catalog has content yet, not by a single generic “cold catalog” condition. Because the status is resolved from your API key before any model call, the response for a given state is deterministic.

The states that return items before training are previews. Every item in a preview is scored exactly 0.0, which is how a client tells a preview apart from personalized results. Previews exist so that your card-rendering code can exercise the real response shape before go-live; they are not a measure of recommendation quality.

For the exact status code, cache behavior, and response body of each state, see Cold-start response states. The Popular and Trending endpoints follow their own recency-backfill rules, described under Graceful degradation.

Why you warm up the model before launch

Getting the integration working proves the plumbing, but a freshly provisioned model knows nothing about your catalog or your audience. Launch on it and readers see generic, popularity-based results.

The fix is to front-load your content catalog and your historical behavioral signal before any reader-facing surface is switched on:

  • Catalog first. A model with no catalog cannot return anything, and new items are placed by their metadata, so a complete back catalog with accurate metadata is the foundation.
  • History next. Replaying historical events gives the model interaction history on day one instead of waiting for live traffic to accumulate it.
  • Then live traffic. Every event your surfaces send after launch continues the warm-up. A deployment that reads recommendations without ever sending events back never improves. See The feedback loop is the product.

The pre-launch steps are laid out phase by phase in the Compass Onboarding Checklist. For the mechanics of seeding your back catalog, see the Sync Your Content Catalog with Compass; for replaying historical events from a Customer Data Platform (CDP) or analytics source, see Forward Events from a CDP or Server.