Introducing Crossing Minds' session-based recommendations - a powerful tool that delivers personalized recommendations in real-time. Our API is capable of analyzing user actions within a session, generating highly relevant recommendations that are tailored to the user's immediate needs and interests.

These recommendations are called session-based recommendations and they are based purely on the user's actions within a single session. This approach allows us to provide highly targeted recommendations that improve engagement and drive sales.

Our session-based endpoint is particularly useful for users who have no history, including new or anonymized users. By analyzing user actions in real-time, we can deliver personalized recommendations that are tailored to the user's current behavior, improving the user experience and increasing revenue growth.

Dashboard Overview

The session-based recommendations feature in Beam Studio is designed to simulate user interactions and behaviors within a single session, delivering personalized recommendations based on these interactions. This innovative approach provides insights into how users' actions influence the recommendations they receive.

Session Simulation

At the top section of the screen, you will find the Session Simulation panel. Here, you can input a series of simulated user interactions or ratings for specific items. These interactions or ratings represent unique actions taken by a user during a session.


The bottom main section of the screen is the Recommendations panel. Here, the real-time recommendations based on the simulated session are displayed. With every new interaction added or rating given in the Session Simulation panel, the Recommendations panel will immediately update to reflect changes in user behavior.

Simulating a Session

To simulate a session:

  1. Click on the 'Add Ratings' button to add a new interaction.
  2. Enter the Item ID that the user interacts with or select one randomly
  3. Add a rating value if it's a 'rate' interaction.
  4. Click 'Submit' to add the interaction to the session.

Each interaction or rating will appear in a chronological list, with the most recent at the top. You can edit or delete interactions at any time during the session.

Evaluating Recommendations

In the bottom main section of the screen, you'll find the user-to-item recommendations tailored for the user in question. By default, this panel displays ten recommendations, offering a balanced overview of our recommender system's output. However, you can adjust this count according to your needs using the dropdown menu located at the top of this panel.

We offer two different views to inspect the recommendations: List View and Grid View.

  1. List View: In this detailed mode, you can see all the properties related to each recommended item. This comprehensive information can provide further insights into why these items were chosen by the system, facilitating a better understanding of our recommendation logic.
  2. Grid View: This mode presents a more visual, compact overview of the recommended items, allowing you to assess the recommendations more swiftly. The Grid View is particularly useful to get a feel of how the recommendations would appear to the user in a carousel or a grid format on your platform.

Recommendation Types

The Beam Studio dashboard is meticulously designed to help you navigate through various features smoothly. A key part of this is the right-side panel, which provides several configurable options to help you tailor your recommendations. Let's go through these features in detail:

On the right-side panel, you will notice three headers, each representing a distinct type of recommendation model that you can evaluate. The availability of these models is based on the custom setup our team has established for you:

  1. Regular: The default recommendation model, shaped by user behavior and preferences, coupled with the business rules you've implemented. This flexible model allows for extensive adjustments to tailor your recommendations.
  2. Context: An advanced recommendation type allowing greater customization. Alongside the standard business rules, you can define 'items' that you want the recommendations to resemble or aim towards, adding an extra layer of personalization.
Note: There's no "Pre-computed Recommendations" option available in session-based recommendations as all recommendations are generated in real-time.

Configuring Business Rules

To adjust the recommendations according to your business needs, Beam Studio provides a set of business rules that you can adapt:

  1. Scenarios: A scenario is a comprehensive set of business rules that provide a strategic framework for your recommendations. Scenarios encapsulate filters, exclusion rules, algorithms, and candidates preselection to produce a tailored recommendation system. You can select the most appropriate scenario for your business model from a predefined set, or even create custom scenarios to cater to specific business requirements. Swapping scenarios allows you to swiftly shift the complete approach of your recommendations before delving into the finer details.
  2. Algorithms: These are the parameters that are fine-tuned to select the most suitable recommendation model. They are usually set by our machine learning engineers.
  3. Filters: Use filters to refine the recommendations by including only items that fulfill certain conditions based on their properties.
  4. Diversity : This unique feature allows you to apply a diversity score to each property of a product. This score influences the variety within the recommendations, allowing you to enhance the breadth of suggestions based on specific attributes, thereby promoting a more diverse product offering.
  5. Exclude Rated Items: Ensure that the items your users have already interacted with (or rated) are not recommended again, keeping their experience fresh and engaging.


Get items recommendations given the ratings or interactions of an anonymous session. Note that the HTTP verb is POST so that ratings can be sent in the body, but the endpoint is stateless as GET. Ratings and interactions are mutually exclusive.

This endpoint supports multiple ways to personalize the recommendations when no history of the user’s item interactions is available, for instance when the user ID itself is not available. The simplest use case is to use an anonymous session ID for which item interactions were previously created. Alternatively, this endpoint also supports sending the item interactions (or equivalently item ratings) directly in the request body.

Compared to the endpoint GET recommendation/users/<str:user_id>/items/, this endpoint is more optimized for capturing short term interactions.

In the special case with no interaction, this endpoint will approximately return the most popular items satisfying the business rules.

Request JSON Object. The following fields can be adjusted in your request:

  • scenario (string) – Optional. Name of scenario to apply. [See About Scenarios]
  • skip_default_scenario (bool) – Optional. Specify whether default scenario should by applied or skipped. [See Default Scenario]
  • cursor (string) – Optional. Pagination cursor, typically from the next_cursor value of the previous response
  • session_id (ID) – Optional. [See Flexible Identifiers], [max_length: 64] Anonymous Session ID. Recommendations will be personalized using the item interactions that were previously created for this anonymous session ID. Also used in the context of an A/B test scenario to select the group A or B and later keep track of the respective group in analytics. Mutually exclusive with providing ratings or user_id.
  • interactions (object-array) – Optional. Item interactions array. Inner fields:
    • item_id (ID) – [See Flexible Identifiers], [max_length: 64] Item ID
    • interaction_type (O) – Interaction Type
    • timestamp (float64) – [min: -150000000000.0 (year -2786) max: 3500000000.0 (year 2080)] Interaction timestamp (default: now)
  • ratings (object-array) – Optional. Item ratings array. Inner fields:

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