# Recommendations

Use `GET /movies/{movie}/recommendations` to find related films. Choose a ranked list of similar movies or explore recommendations grouped into themed threads.

## Similar movies

The default mode is `similar`:

```sh
curl --get "$ATM_API_BASE_URL/movies/$ATM_MOVIE_ID/recommendations" \
  --header "Authorization: Bearer $ATM_API_KEY" \
  --data-urlencode 'mode=similar' \
  --data-urlencode 'limit=10'
```

Each result is a movie record with `rank` and `score`. Preserve the returned ordering when displaying recommendations. A score is recommendation metadata, not a critic rating or a percentage match.

You can narrow results with `genre`, `year_from`, and `year_to`. Keep these filters when following a pagination cursor.

## Explore themed threads

```sh
curl --get "$ATM_API_BASE_URL/movies/$ATM_MOVIE_ID/recommendations" \
  --header "Authorization: Bearer $ATM_API_KEY" \
  --data-urlencode 'mode=threads' \
  --data-urlencode 'limit=10'
```

Each thread contains an `id`, `title`, `description`, `type`, `strength`, and a `movies` page. Use the title and description to explain the connection to your reader. The embedded movie list is a preview of up to five movies.

## Open one thread

Set `ATM_THREAD_ID` to an ID returned for this movie, then request its movies directly:

```sh
curl --get "$ATM_API_BASE_URL/movies/$ATM_MOVIE_ID/recommendations" \
  --header "Authorization: Bearer $ATM_API_KEY" \
  --data-urlencode 'mode=threads' \
  --data-urlencode "thread_id=$ATM_THREAD_ID" \
  --data-urlencode 'limit=20'
```

This returns a paginated list of movies for the selected thread. Follow that response's `next_cursor` on the same URL with `mode=threads` and the same `thread_id`. A thread ID must belong to the movie in the path; otherwise the request returns `404`.

## Handle an empty recommendation list

Not every movie has recommendations or threads. A successful empty list means there are no matching results. Offer another search or a [collection](/related-resources#collections) in your interface rather than treating it as an API failure.

**Next:** [Pagination →](/pagination)