# List recommended videos

`GET /api/v1/recommendations/videos`

Return videos recommended next to a reference video (or general recommendations if no reference video is given).

PeerTube decides the recommendation algorithm: it currently lists videos sharing tags with the reference video
(excluding videos already watched by the authenticated user), then the latest videos.
All returned videos are restricted to the `scope`, which defaults to the `recommendationScope` of the reference video.


Authentication: no security requirement declared for this operation.

Parameters:

- `scope` (query, VideoRecommendationScopeSet, optional) - Restrict recommended videos. Defaults to the `recommendationScope` of the reference video, or to `1` (all videos) if no reference video is given

  Type: VideoRecommendationScopeSet
  
  Videos that can be recommended next to a video:
    - `1` All videos
    - `2` Only videos of the platform that owns the reference video (or of the current platform if no video is given)
    - `3` Only videos of the account that owns the reference video
    - `4` Only videos of the channel of the reference video
  
  This is a preference of the video owner: applications displaying recommendations may not apply it
  
  
  Schema: [VideoRecommendationScopeSet](https://sourcey-peertube.pages.dev/api-rest-reference/models/videorecommendationscopeset.md)
  
  enum: [1,2,3,4]

- `videoId` (query, id | UUIDv4 | shortUUID, optional) - Reference video. Required if `scope` is `3` or `4`
  Type: id | UUIDv4 | shortUUID
  
  oneOf:
    Reference: [id](https://sourcey-peertube.pages.dev/api-rest-reference/models/id.md); Type: id
    
    minimum: 1
    
    Example:
    
    ```json
    42
    ```
  
    Reference: [UUIDv4](https://sourcey-peertube.pages.dev/api-rest-reference/models/uuidv4.md); Type: UUIDv4, uuid
    
    minLength: 36
    
    maxLength: 36
    
    pattern: "^[0-9a-f]{8}-[0-9a-f]{4}-[0-9a-f]{4}-[0-9a-f]{4}-[0-9a-f]{12}$"
    
    Example:
    
    ```json
    "9c9de5e8-0a1e-484a-b099-e80766180a6d"
    ```
  
    Reference: [shortUUID](https://sourcey-peertube.pages.dev/api-rest-reference/models/shortuuid.md); Type: shortUUID
    
    translation of a uuid v4 with a bigger alphabet to have a shorter uuid
    
    Example:
    
    ```json
    "2y84q2MQUMWPbiEcxNXMgC"
    ```

- `count` (query, integer, optional) - Number of videos to return
  Type: integer
  
  default: 10
  
  minimum: 1
  
  maximum: 30

- `excludeVideoIds` (query, Array<id>, optional) - Videos that must not be recommended (the reference video is always excluded)
  Type: Array<id>
  
  maxItems: 50
  
  Items:
    Reference: [id](https://sourcey-peertube.pages.dev/api-rest-reference/models/id.md); Type: id
    
    minimum: 1
    
    Example:
    
    ```json
    42
    ```

- `x-peertube-video-password` (header, string, optional) - Required on password protected video
  Type: string

- `nsfw` (query, string, optional) - whether to include nsfw videos, if any
  Type: string
  
  enum: ["true","false"]

- `nsfwFlagsIncluded` (query, NSFWFlag, optional)
  Type: NSFWFlag
  
  
  NSFW flags (can be combined using bitwise or operator)
  - `0` NONE
  - `1` VIOLENT
  - `2` EXPLICIT_SEX
  
  
  Schema: [NSFWFlag](https://sourcey-peertube.pages.dev/api-rest-reference/models/nsfwflag.md)
  
  enum: [0,1,2,4]

- `nsfwFlagsExcluded` (query, NSFWFlag, optional)
  Type: NSFWFlag
  
  
  NSFW flags (can be combined using bitwise or operator)
  - `0` NONE
  - `1` VIOLENT
  - `2` EXPLICIT_SEX
  
  
  Schema: [NSFWFlag](https://sourcey-peertube.pages.dev/api-rest-reference/models/nsfwflag.md)
  
  enum: [0,1,2,4]

- `aiUsageOneOf` (query, VideoAIUsageSet | Array<VideoAIUsageSet>, optional) - **PeerTube >= 9.0** Only list videos with one of these AI usages, declared by video creators.
If not provided, the preference of the authenticated user (`aiUsagesHidden`) is used

  Type: VideoAIUsageSet | Array<VideoAIUsageSet>
  
  oneOf:
    Reference: [VideoAIUsageSet](https://sourcey-peertube.pages.dev/api-rest-reference/models/videoaiusageset.md); Type: VideoAIUsageSet
    
    **PeerTube >= 9.0** Use of AI in the video, declared by the video creator:
      - `1` Not specified
      - `2` No AI-generated content: nothing seen or heard in the video has been generated by AI
      - `3` Contains AI-generated content: some parts of the video have been generated by AI
      - `4` AI-generated: the whole video, or most of it, has been generated by AI
    
    
    enum: [1,2,3,4]
  
    Type: Array<VideoAIUsageSet>
    
    Items:
      Reference: [VideoAIUsageSet](https://sourcey-peertube.pages.dev/api-rest-reference/models/videoaiusageset.md); Type: VideoAIUsageSet
      
      **PeerTube >= 9.0** Use of AI in the video, declared by the video creator:
        - `1` Not specified
        - `2` No AI-generated content: nothing seen or heard in the video has been generated by AI
        - `3` Contains AI-generated content: some parts of the video have been generated by AI
        - `4` AI-generated: the whole video, or most of it, has been generated by AI
      
      
      enum: [1,2,3,4]

Responses:

- 200: successful operation

Content type: application/json

Type: VideoListResponse

Schema: [VideoListResponse](https://sourcey-peertube.pages.dev/api-rest-reference/models/videolistresponse.md)

- `total` (optional)
  Type: integer
  
  Example:
  
  ```json
  1
  ```

- `data` (optional)
  Type: Array<Video>
  
  maxItems: 100
  
  Items:
    Reference: [Video](https://sourcey-peertube.pages.dev/api-rest-reference/models/video.md); Type: Video

- 400: invalid parameters or missing `videoId`

- 401: reference video requires authentication or a password

- 403: reference video is not visible by the user or the password is invalid

- 404: reference video not found

## Examples

### cURL

```bash
curl -X GET 'https://peertube2.cpy.re/api/v1/recommendations/videos?count=10'
```

### JavaScript

```javascript
const response = await fetch('https://peertube2.cpy.re/api/v1/recommendations/videos?count=10', {
  method: 'GET',
});

const data = await response.text();
```

### Python

```python
import requests

response = requests.get('https://peertube2.cpy.re/api/v1/recommendations/videos?count=10')
print(response.text)
```