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

{% hint style="info" %}
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.
{% endhint %}

## 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:

```javascript
{
    "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:

<table><thead><tr><th width="174">source_id</th><th width="226">target_id</th><th width="81">#</th><th width="144">score</th></tr></thead><tbody><tr><td>user_0001</td><td>Lost World</td><td>1</td><td>0.91</td></tr><tr><td>user_0001</td><td>Rick &#x26; Morty S1-1</td><td>2</td><td>0.86</td></tr><tr><td>user_0001</td><td>Alien</td><td>3</td><td>0.84</td></tr><tr><td>...</td><td>...</td><td>...</td><td>...</td></tr><tr><td>user_0001</td><td>Titanic</td><td>100</td><td>0.61</td></tr><tr><td>user_0002</td><td>Jurassic Park</td><td>1</td><td>0.83</td></tr><tr><td>...</td><td>...</td><td>...</td><td>...</td></tr></tbody></table>

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:

```javascript
{
    "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:

```javascript
{
    "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!

```javascript
{
    "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:

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

#### Response format

<table><thead><tr><th width="227">Field</th><th width="98">Type</th><th>Description</th></tr></thead><tbody><tr><td><code>source_id</code></td><td>str</td><td>The entity for which recommendations are being made</td></tr><tr><td><code>target_id</code></td><td>str</td><td>The recommended entity ID</td></tr><tr><td><code>score</code></td><td>float</td><td>The recommendation score, ranging from 0-100</td></tr></tbody></table>


---

# Agent Instructions: Querying This Documentation

If you need additional information that is not directly available in this page, you can query the documentation dynamically by asking a question.

Perform an HTTP GET request on the current page URL with the `ask` query parameter:

```
GET https://lucid-ai.gitbook.io/devdocs/products/recommendation/how-to-guide/get-recommendations.md?ask=<question>
```

The question should be specific, self-contained, and written in natural language.
The response will contain a direct answer to the question and relevant excerpts and sources from the documentation.

Use this mechanism when the answer is not explicitly present in the current page, you need clarification or additional context, or you want to retrieve related documentation sections.