Get Recommendations

With a trained model, you can quickly get many types of recommendations for different entity types. Recommendations can be pulled in real-time or in batches through our API.

We generally recommend doing batched recommendation queries where possible to cache results and minimize latency for serving recommendations. While our query latency times are very low, caching the recommendations eliminates it entirely.

Querying recommendations

You can query for a recommendation using the /recommended_items endpoint. This endpoint allows you to specify the entity or entity types you want recommendations for, and the entity types you want to be recommended. For example, consider the following recommendation query parameters:

{
    "model_id": "<your model id>"
    "source_type": "user",
    "target_type": "video",
    "max_recommendations": 100,
    "output_format": "csv"
}

This query will ask for recommendations for all users, where the recommended content are video entities. Up to 100 recommendations per user will be generated, ordered by score (highest-to-lowest). The returned recommendations might look something like this:

source_id	target_id	#	score
user_0001	Lost World	1	0.91
user_0001	Rick & Morty S1-1	2	0.86
user_0001	Alien	3	0.84
...	...	...	...
user_0001	Titanic	100	0.61
user_0002	Jurassic Park	1	0.83
...	...	...	...

Note that this query is returning recommendations for all users instead of just a single user. If you instead want to just get recommendations for a particular user, the query would be:

{
    "model_id": "<your model id>",
    "source_id": "user_0001",
    "target_type": "video",
    "max_recommendations": 100,
    "output_format": "json"
}

And for multiple, specific users it would be:

{
    "model_id": "<your model id>",
    "source_id": ["user_0001", "user_0002"],
    "target_type": "video",
    "max_recommendations": 100,
    "output_format": "json"
}

You can even specify different target entity types as needed. For example, if you want to recommend writers to a user, you can use the following query. Having a single graph neural network trained on your data allows a huge variety of simple recommendations!

{
    "model_id": "<your model id>",
    "source_type": "user",
    "target_type": "writer",
    "max_recommendations": 100,
    "output_format": "json"
}

Query specification

Request format

To query recommendations, the following parameters are permitted:

Parameter	Type	Description
model_id	str	The unique ID for your recommender model
source_id	str | list[str]	An optional entity ID or list of IDs to get recommendations for.
source_type	str | list[str]	An optional entity type or list of types to get recommendations for. Either this parameter or the entity_id parameter must be specified.
target_type	str | list[str]	An entity type or list of entity types to recommend.
max_recommendations	int	The maximum number of recommendations to return per entity. Defaults to 100.
threshold	float	An optional minimum recommendation score threshold. Defaults to 0. Must range between 0-100.
output_format	str	Denotes whether results should be returned in CSV or JSON format.

Response format

Field	Type	Description
source_id	str	The entity for which recommendations are being made
target_id	str	The recommended entity ID
score	float	The recommendation score, ranging from 0-100