Scenarios

You can configure different recommendation behaviors for each scenario and then monitor their performance in the KPI section and the Insights.

Setting Up a Scenario

In the Recombee Admin UI, navigate to the Scenarios section. Choose Create Scenario and enter a name for your new scenario.

Then, select its Type:

Ranked List

• Returns a single set of recommended items, users, or Item Segments.
• Ideal for typical recommendation and search use cases.

Composite

• Suitable for cases such as Because You Watched <movie> or Items from <category> for You.
• Produces a composite response with two parts:
  • Source — a single item, user, or Item Segment
  • Result — a set of recommended items, users, or Item Segments related to the Source
• See Composite Recommendations for more details.

Requesting a Scenario

Use the Scenario in API Requests or No-Code Widgets.

When using the API:

• Pass the name of the created scenario to the scenario parameter of the recommendation request.
• Example for scenario homepage:

const result = await client.send(
  new recombee.RecommendItemsToUser(userId, count, {
    scenario: 'homepage',
  })
);

val request = RecommendItemsToUser(
    userId = userId,
    count = count,
    scenario = "homepage"
)
val result = client.sendAsync(request)

let request = RecommendItemsToUser(
    userId: userId,
    count: count,
    scenario: "homepage"
)
let result = try await client.send(request)

const result = await client.send(
  new rqs.RecommendItemsToUser(userId, count, {
    scenario: 'homepage',
  })
);

result = client.send(RecommendItemsToUser(user_id, count, scenario='homepage'))

result = client.send(RecommendItemsToUser.new(userId, count, {
  'scenario' => 'homepage'
}))

RecommendationResponse result = client.send(
  new RecommendItemsToUser(userId, count).setScenario("homepage")
);

$result = $client->send(new RecommendItemsToUser($user_id, $count, [
  'scenario' => 'homepage'
]));

RecommendationResponse result = client.Send(
    RecommendItemsToUser(userId, count, scenario: "homepage")
);

req := client.NewRecommendItemsToUser(userId, count).SetScenario("homepage")
recommRes, err := req.Send()

GET /{databaseId}/recomms/users/userId/items/?count=10&scenario=homepage

Scenario Settings in the Admin UI

You can customize each scenario individually.

Logic

Logic defines the behavior of the recommendation model.

Filters

Filters determine which items can be recommended in this scenario. You can select filters from the Recombee library or create your own Business Rules.

An item can be recommended only if all filter rules assigned to the scenario are satisfied.

Global Settings

To apply filters to all scenarios, use Global Settings—for example, to always exclude unavailable items.

Rules defined in Global Settings are applied automatically to all scenarios, ensuring consistency across your application.

Boosters

Boosters allow you to prioritize certain items within a scenario to support your business goals. You can use predefined booster rules or create your own Business Rules.

Each booster rule produces a numeric score for each item. The final boosting score is the product of the scores from all applied booster rules.

Constraints

Constraints define how frequently items sharing certain conditions can appear in recommendation results.

Examples:

• At most 2 items per category
• No more than 50% of items from a single genre
• Only one product per parent product ID

To use constraints, first create an Item Segmentation that represents the shared condition (e.g., category, genre, or brand).

Then, add the constraint to your scenario and set how many items per segment are allowed in the recommendations.

Limit Type

• Absolute — sets a fixed number of items per segment (e.g., max 3 per brand).
• Percentage — sets a proportion (e.g., max 25% from one brand).

Window Size

When using the Absolute limit type, the limit applies to all recommended items by default. To apply it to smaller groups, set a window size.

For example, with a max of 2 items per segment and a window size of 4, each consecutive group of 4 recommendations will contain at most 2 from the same segment.

Composite Recommendations

Composite Recommendations return both a source entity (e.g., an Item or Item Segment) and a related list of recommendations in a single response.

They are requested via the Composite Recommendation API endpoint.

Examples

Because You Watched <movie>

• Source: The movie (Item) watched by the user
• Result: Movies related to the watched one

Articles from <category>

• Source: The user’s favorite category (Item Segment)
• Result: Recommended articles from that category

Artists Related to <artist>

• Source: The user’s favorite artist (Item Segment)
• Result: Recommended artists related to the favorite artist

Fully Personalized Homepage

Often, multiple Composite Recommendations are requested in a Batch to fully personalize the homepage or other sections of a website or app.

For example, to display five rows on the homepage — each representing one of the user’s top five categories and showing the most relevant content within that category — you can send five Composite Recommendation requests in a single Batch, set as:

• Source: category (Item Segment)
• Result: content (Items)

This approach enables the homepage to consist of dynamically personalized sections.

The API automatically ensures that five distinct categories are returned in the response, avoiding duplicates.

See the API code example for implementation details.

Structure

Composite Recommendations can be viewed as two sequential requests:

1. Recommend the Source.
2. Recommend the Result for that Source.

For instance, Articles from <category> involves:

• Recommend Item Segments To User to find the category.
• Recommend Items To Item Segment to get articles from that category.

Each Composite Recommendation counts as one API request for billing.

Setup Mode

When creating a Composite Recommendation scenario, you can choose a Template or a Custom configuration.

Templates

Predefined templates are available for common cases such as Because You Purchased or Videos From Top Genre For You. Templates define both the endpoints used for each stage and the Logic.

Custom

Custom configuration allows you to manually define the endpoints for each stage and assign different Logics as needed.

Configuration

In the Admin UI, you can set distinct Filters and Boosters for each stage (Source and Result).

You can also specify these settings using the sourceSettings and resultSettings API parameters.

A/B Testing

A/B Testing lets you compare different recommendation configurations within a Scenario and measure their effect on your key metrics. Each experiment runs on top of a specific Scenario, with traffic split between a Control (the current Scenario configuration) and one or more Variants.

Setting Up an Experiment

You can create an experiment either from the A/B Testing tab inside a Scenario's detail view, or from the standalone A/B Testing section in the Admin UI.

When creating an experiment, provide a title (or leave it blank to have one generated automatically), then select the Scenario it should run on. Set the start date — and optionally an end date — to define the experiment's time window.

Metrics

Metrics define what you want to measure. You must choose at least one metric before the experiment can be created.

Recombee provides a library of predefined metrics organized by vertical (Video, E-Commerce, Articles & News, etc.) — including metrics such as Conversion Rate, Click-Through Rate (CTR), Watch Time from Recommendations, and Income from Recommendations.

You can also create custom metrics based on Insights. A custom metric lets you specify a data source (e.g., Detail Views from Recommendations) and apply filters — for example, to track views from recommendations only for items from a particular category, or to measure the purchase rate exclusively for items above a certain price threshold.

Variants

Each experiment has a Control — the Scenario's current configuration — and one or more Variants that modify it.

When creating a Variant, you can change any combination of:

• Logic — the whole recommendation model ensemble or its individual parameters
• Filters — which items are eligible to be recommended
• Boosters — how items are ranked within results
• Constraints — limits on how frequently certain Segment of items appear

The Admin UI clearly shows what has been changed in each Variant relative to the Control.

Once Variants are defined, assign a traffic allocation (percentage) to each using the sliders. Use the lock icon to fix a Variant's allocation so it is not affected when adjusting others. Click Distribute Evenly to split traffic equally across all Variants.

Report

The report shows the effect of each Variant on every selected metric, including whether the results are statistically significant. For each metric, the table displays:

• Users — number of users in the Variant and their share of total traffic
• Improvement — change relative to the Control baseline
• Probability to be best — likelihood that this Variant outperforms all others
• Probability to beat baseline — likelihood that this Variant outperforms the Control
• Distribution — the mean and variance of the metric's value across users

The best-performing Variant is highlighted in the results.