Welcome to Shaped. Shaped is an API for ranking. It is designed for developers that want to implement discovery features like feeds, recommendations or notifications. No machine-learning experience is required to get started with Shaped, you simply setup a Shaped model from the command line and start getting personalized, highly engaging results for your users.

These docs explain everything you need to know to get started with Shaped. We recommend you read through this overview first, then move on to the Quickstart, Tutorials and API reference.

What is ranking?

Before diving into how Shaped works, let’s define what we mean by ranking. A ranking is:

An optimal ordering of items surfaced to your users

The item can be anything you’d want to show to your user in a product or website. It could be a post, video, image, music, documents, notifications, products or even other users (e.g. “People you may follow” widgets).

The optimal ordering is different for every use-case. For example a media company may want to increase the time-spent on their platform and an e-commerce company might want to increase product purchase conversions. This optimal ordering may also be different for every user, which is why rankings are typically personalized.

At Shaped we keep this definition relatively general so that we can put the power in the hands of you — the developer. You can choose what to optimize for and the items you want to rank; we handle everything else.

How Shaped works?

1. Connect your data stack

Shaped securely connects to your database (e.g. Postgres, MySQL) or data warehouse (e.g. BigQuery, Redshift) enabling it to periodically ingest the data needed for training your ranking model.

2. Set your user, item and interaction schema

Once connected, Shaped ingests your user, item and user-item interaction data for training.

  • The users are needed so that we can provide personalized results. When you fetch the rankings, you specify what user you want results for and we’ll return the optimal ranking for them.
  • The items are what you want to be surfaced to the users. For a product like TikTok, this could be the videos within the feed. For a marketplace like Airbnb, this could be the listings displayed to each user.
  • The interactions are the events that relate the users and items together. These contain the behavioral information necessary to learn what types of users like what types of items. Furthermore, they indicate the interaction objective that’s being optimized. For example, if you specify the interaction type as “clicks”, the ranking model will learn which users are more likely to click which content.


Often in recommendation systems you optimize auxiliary objectives (e.g “clicks”, “add-to-cart”) with the hopes that it will correlate with the final business metric (e.g daily-active users or revenue). You have the freedom to explore different interaction types that you expect will lead to an improvement in the final business metrics.

3. Model training & deployment

Based on the schema you provide, Shaped ingests the user, item and interaction data and starts training a custom ranking model. The model type is decided from your specific schema types and format. For example, if the item schema you provided has an image column, we use a pre-trained image model architecture to extract the features that matter from the pixels.


Although the documentation references one ranking model, in practice we use several models to provide your ranked results. We use models to automatically derive features from your data types, models to generate a subset of candidates that we should rank, and finally a model to score each item in the final candidate list. The sorted order of this final scoring model are the results that you see when you fetch your ranked results.

4. Start fetching ranked results

After a few hours your newly minted ranking model will be deployed to a custom endpoint that you can fetch results from. We provide an API that you can integrate directly into your product so that your users can see the items that are best for them.

5. Continuous training

Your ranking model is continuously trained (up to a 4 hour frequency) to ensure that it keeps learning from the freshest interactions. This helps avoid data drift for example caused by seasonality or trends within your data.