---
title: "GET /polls/{name}/recommendations/"
method: GET
path: "/polls/{name}/recommendations/"
tags: ["polls"]
---

# GET /polls/{name}/recommendations/

`GET /polls/{name}/recommendations/`

List the recommended entities of a given poll sorted by decreasing total
score.

## Path parameters

- `name` string, required

## Query parameters

- `limit` integer
- `offset` integer
- `date_lte` string, date-time
- `date_gte` string, date-time
- `search` string
- `unsafe` boolean
- `exclude_compared_entities` boolean
- `weights` object
- `metadata` object
- `score_mode` 'all_equal' | 'default' | 'trusted_only'

## Response `200`

- PaginatedRecommendationList
  - `count` integer, required
  - `next` string, uri, nullable
  - `previous` string, uri, nullable
  - `results` Recommendation[], required
    - `entity` RelatedEntity, required — An Entity serializer that will lookup and possibly create the Entity object on validation, if it does not exist in the database yet. Only the field `uid` is provided when using write HTTP methods. Used by ModelSerializer(s) having one or more nested relations with Entity, and having the constraint to ensure that entity instances exist before they can be saved properly.
      - `uid` string, required
      - `type` 'video' | 'candidate_fr_2022', required — * `video` - Video * `candidate_fr_2022` - Candidate (FR 2022)
      - `metadata` object, required
    - `entity_contexts` EntityContext[], required
      - `origin` 'ASSOCIATION' | 'CONTRIBUTORS' — * `ASSOCIATION` - Association * `CONTRIBUTORS` - Contributors
      - `unsafe` boolean — If True, this context will make the targeted entities unsafe.
      - `text` string, required
      - `created_at` string, date-time, required
    - `collective_rating` ExtendedCollectiveRating, required
      - `n_comparisons` integer, required — Total number of pairwise comparisons for this entityfrom certified contributors
      - `n_contributors` integer, required — Total number of certified contributors who rated the entity
      - `tournesol_score` number, double, nullable, required — The aggregated score of the main criterion for all users, in a specific poll.
      - `unsafe` UnsafeStatus, required
        - `status` boolean, required
        - `reasons` ReasonsEnum[], required
      - `criteria_scores` EntityCriteriaScore[], required
        - `criteria` string, required — Name of the criteria
        - `score` number, double — Score of the given criteria
    - `recommendation_metadata` RecommendationMetadata, required
      - `total_score` number, double, nullable, required

## Changes

- **2024-12-19** `3bba1a8d6651` — 2 info
  - the response property `count` became required for the status `200`
  - the response property `results` became required for the status `200`
- **2023-11-30** `834066e5d795` — 1 warning, 1 info
  - added the new `moderation_by_contributors` enum value to the `results/items/collective_rating/allOf[#/components/schemas/ExtendedCollectiveRating]/unsafe/allOf[#/components/schemas/UnsafeStatus]/reasons/items/` response property for the response status `200`
  - added the required property `results/items/entity_contexts` to the response with the `200` status
- **2023-11-22** `8e45c6d6f248` — 1 warning
  - added the new `moderation_by_association` enum value to the `results/items/collective_rating/allOf[#/components/schemas/ExtendedCollectiveRating]/unsafe/allOf[#/components/schemas/UnsafeStatus]/reasons/items/` response property for the response status `200`
- **2023-09-28** `9671427c6f2e` — 9 breaking, 3 info
  - removed the required property `results/items/criteria_scores` from the response with the `200` status
  - removed the required property `results/items/metadata` from the response with the `200` status
  - removed the required property `results/items/n_comparisons` from the response with the `200` status
  - removed the required property `results/items/n_contributors` from the response with the `200` status
  - …8 more
- …earlier changes not shown

[Full history](https://skmtc.dev/tournesol-app/apis/tournesol-api/changes/polls/:name/recommendations/get.md)

---

[API](https://skmtc.dev/tournesol-app/apis/tournesol-api.md) · [All operations](https://skmtc.dev/tournesol-app/apis/tournesol-api/llms.txt) · [OpenAPI document](https://skmtc-service-production.skmtc.workers.dev/v1/apis/tournesol-app/tournesol-api/revisions/96c8c62ad972/schema)