Scenarios

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

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:

Standard

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

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:

client.send(new recombee.RecommendItemsToUser(userId, count, {
  scenario: 'homepage',
}), callback);

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)

var recombee = require('recombee-api-client');
var rqs = recombee.requests;

client.send(new rqs.RecommendItemsToUser(userId, count, {
scenario: 'homepage'
}), callback);

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.

Business Rules

The Business Rules section in the Admin UI lets you create Filter and Booster rules using the ReQL language.

You can also use the AI ReQL Code Assistant to generate rules from natural language input.

For example, you can create a rule to recommend only short (<30 minutes) English-language movies:

If you have multiple scenarios requiring different limits, you can make certain values (e.g., max runtime) configurable via input parameters:

When applying such a rule to a scenario, you can specify the desired input (e.g., runtime in minutes):

See the ReQL documentation and tutorial for details.

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.