Item Filters

The most straighforward and simplest way to leverage your item filters is to head to your Recommendations sections and open any recommendation tab.


Beam Studio Dashboard offers you the ability to fine-tune the recommendations through an array of pre-configured algorithms. You can seamlessly switch between these algorithms to adjust the output based on your business needs and strategic goals.

These algorithms work behind the scenes to optimize the quality of your recommendations, improving user engagement and driving business outcomes. By incorporating your unique business rules, you can ensure that the recommendations are personalized and relevant. Details on how to utilize this feature are outlined further in this documentation.


At times, you may want to have recommendations on items satisfying certain criteria: a price range, the release year of a movie, a minimal popularity, some internal business rule… Filters are provided for this task, enabling your client to dynamically preselect items based on their properties. They are a type of business rules.

Naturally, the richer the items properties, the better the filter, but that’s only the tip of the iceberg since this feature is useful at two different levels:

  • You can create server-side business rules, such as displaying only new TV-shows in some sections of your app.
  • You can hand over control to your end user with buttons and switches, so they can configure themselves what they see. Think price range, clothes’ color, category, brand or platform.

Keep in mind that each filter applies to only one item-property; you can then combine multiple filters together, resulting in the intersection of all.

Below, we first present the syntax of filters (the two ways to use them) before moving on to their logic to see what each filter operator does and how to combine them.

Exclude Rated Items

For GET recommendation/users/<str:user_id>/items/ or POST recommendation/sessions/items/ recommendations, rated items can be excluded from the returned items.

Reranking & Diversity

Reranking rules reorder the recommended items according to their property values.

It is often useful – if not necessary – to reorder recommended items following some criteria on the items’ properties. The reranking option does just that, to add some diversity or bring forth some items. It applies some pre-defined rules to calculate scores on the items recommended to rerank them. Thus it is a type of Business Rule. It may change the recommended items, given that the reranking happens before the final item selection.

Similarly to the filters option, you need to provide a property_name, the op of reranking, and possibly a positive weight to specify the importance of the rule and some more options.

Important note: reranking does not affect the models nor the training; it simply modifies the recommendations provided by a model. See Algorithms for more information about models.

Reranking & Diversity - Advanced & API Only

The following section is for API use only and not through Beam Studio

API Options

The diversity reranking offers the following options:

  • default_malus: a positive score to attribute to items missing the item-property we add diversity to. Defaults to 0.
  • activation_period: positive integer to activate the lack-of-diversity malus only every k repetitions of a property value. Combined with a large weight, this practically enforces that at most k consecutive items with the same property value can be recommended. Defaults to 1.


The following reranking rule almost enforces that the recommendations will contain a new genre every two items. URL-string version: genres:diversity:2:activation_period:2:default_malus:0.5.

Object version:

  "property_name": "genres",
  "op": "diversity",
  "weight": 2,
  "options": {
    "activation_period": 2,
    "default_malus": 0.5


When you see that the recommendations you get are not diverse enough, you can add a diversity reranking on an item-property of interest. For example,

Copied to clipboard!
    	"property_name": "genres",
    	"op": "diversity",
    	"weight": 1,
    	"options": {
      	"activation_period": 2

does the following:

  • attribute a malus to each item depending on how much its genres were found in previous items among recommended items, with a default_malus of 0 for missing properties;
  • rerank the items according to their new internal score and provided weight.

The weight and the activation_period have different effects. We recommend experimenting with these two parameters as an appropriate value is database-dependent.

The weight specifies the importance we give to having a substantial diversity, compared to keeping the original ranking: weight=0 will add no diversity, weight=1 makes the diversity reasonably strong, weight=10 makes it strongly predominant,

The activation_period parameter enables groups with the same property value to be recommended consecutively. It decreases diversity, but it is often not an issue to have two or three comedy movies recommended in a row as long as all movies recommended are not comedies. A reranking rule genres:diversity:2:activation_period:3 does just that: it activates the lack-of-diversity malus only every three repetitions of a property value.

The default_malus option specifies the default score for items that have no value for the item-property to apply diversity on.

Even though diversity applies to numerical properties (for example, the year a movie came out or on the price of the items), the activation_period parameter only affects categorical properties.

Self-Referencing Filters

With the current setup and filters that we have in place, we need to consider more “dynamic” filters that are evolving and adapting to the different users or items as input when calling the API.

For instance, in the situation where a business wants to recommend only more expensive products than the item seen by a user they can not create a scenario with a “hard value” for the price since every item has a different value. Instead, they will consider building a scenario with “dynamic” business rules that adapt to every case and only recommend products with a price “higher than the initial product price”


You can ONLY create a self reference filter in the Item-to-items scenario case section

When entering a filter value, the front will have to create a JSON with the following keys

the type for item-to-items recommendations would be item_property and the value can be any of the properties of the items that are of the same type as the property_name selected.

If the property_name selected is int then the value in the property section

Scenarios Set Up

First , let's go to your scenario tab in your dashboard.

For a user to create a self-referring filter, the users need will need to start entering a value by typing “#”

Once a user enters this symbol, the dashboard will list all the possible self-referencing values that can be entered aka all the properties of the items that are of the same type that the property_name entered for this filter.  

In the example below, the year is an int and therefore when the user enter # then the front will need to list all the int properties

Multiple options can be selected.

Get started with Crossing Minds recommendation API

Crossing Minds Recommendation API is the easiest way to integrate personalized recommendation to your website & mobile apps

Thank you! Your submission has been received!
Oops! Something went wrong while submitting the form.
On this page
We use cookies (and other similar technologies) to collect data in order to improve our site. You have the option to opt-in or opt-out of certain cookie tracking technologies.To do so, click here.


API Documentation Center,
please wait a bit...