# Search videos `GET /api/v1/search/videos` Authentication: no security requirement declared for this operation. Parameters: - `search` (query, string, required) - String to search. If the user can make a remote URI search, and the string is an URI then the PeerTube instance will fetch the remote object and add it to its database. Then, you can use the REST API to fetch the complete video information and interact with it. Type: string - `uuids` (query, any, optional) - Find elements with specific UUIDs Type: any Items: Type: string - `searchTarget` (query, string, optional) - If the administrator enabled search index support, you can override the default search target. **Warning**: If you choose to make an index search, PeerTube will get results from a third party service. It means the instance may not yet know the objects you fetched. If you want to load video/channel information: * If the current user has the ability to make a remote URI search (this information is available in the config endpoint), then reuse the search API to make a search using the object URI so PeerTube instance fetches the remote object and fill its database. After that, you can use the classic REST API endpoints to fetch the complete object or interact with it * If the current user doesn't have the ability to make a remote URI search, then redirect the user on the origin instance or fetch the data from the origin instance API Type: string enum: ["local","search-index"] - `start` (query, integer, optional) - Offset used to paginate results Type: integer minimum: 0 - `count` (query, integer, optional) - Number of items to return Type: integer default: 15 minimum: 1 maximum: 100 - `skipCount` (query, string, optional) - if you don't need the `total` in the response Type: string default: "false" enum: ["true","false"] - `sort` (query, string, optional) Type: string Sort videos by criteria (prefixing with `-` means `DESC` order): * `hot` - Adaptation of Reddit "hot" algorithm taking into account video views, likes, dislikes and comments and publication date * `best` - Same than `hot`, but also takes into account user video history * `trending` - Sort videos by recent views ("recent" is defined by the admin) * `views` - Sort videos using their `views` counter * `publishedAt` - Sort by video publication date (when it became publicly available) enum: ["name","-duration","-createdAt","-publishedAt","-views","-likes","-comments","-trending","-hot","-best"] - `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, 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 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 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] - `isLive` (query, boolean, optional) - whether or not the video is a live Type: boolean - `includeScheduledLive` (query, boolean, optional) - whether or not include live that are scheduled for later Type: boolean - `categoryOneOf` (query, VideoCategorySet | Array, optional) - category id of the video (see [/videos/categories](#operation/getCategories)) Type: VideoCategorySet | Array oneOf: Reference: [VideoCategorySet](https://sourcey-peertube.pages.dev/api-rest-reference/models/videocategoryset.md); Type: VideoCategorySet category id of the video (see [/videos/categories](#operation/getCategories)) Example: ```json 15 ``` Type: Array Items: Reference: [VideoCategorySet](https://sourcey-peertube.pages.dev/api-rest-reference/models/videocategoryset.md); Type: VideoCategorySet category id of the video (see [/videos/categories](#operation/getCategories)) Example: ```json 15 ``` - `licenceOneOf` (query, VideoLicenceSet | Array, optional) - licence id of the video (see [/videos/licences](#operation/getLicences)) Type: VideoLicenceSet | Array oneOf: Reference: [VideoLicenceSet](https://sourcey-peertube.pages.dev/api-rest-reference/models/videolicenceset.md); Type: VideoLicenceSet licence id of the video (see [/videos/licences](#operation/getLicences)) Example: ```json 2 ``` Type: Array Items: Reference: [VideoLicenceSet](https://sourcey-peertube.pages.dev/api-rest-reference/models/videolicenceset.md); Type: VideoLicenceSet licence id of the video (see [/videos/licences](#operation/getLicences)) Example: ```json 2 ``` - `languageOneOf` (query, VideoLanguageSet | Array, optional) - language id of the video (see [/videos/languages](#operation/getLanguages)). Use `_unknown` to filter on videos that don't have a video language Type: VideoLanguageSet | Array oneOf: Reference: [VideoLanguageSet](https://sourcey-peertube.pages.dev/api-rest-reference/models/videolanguageset.md); Type: VideoLanguageSet language id of the video (see [/videos/languages](#operation/getLanguages)) Example: ```json "en" ``` Type: Array Items: Reference: [VideoLanguageSet](https://sourcey-peertube.pages.dev/api-rest-reference/models/videolanguageset.md); Type: VideoLanguageSet language id of the video (see [/videos/languages](#operation/getLanguages)) Example: ```json "en" ``` - `tagsOneOf` (query, string | Array, optional) - tag(s) of the video Type: string | Array oneOf: Type: string Type: Array maxItems: 5 Items: Type: string - `tagsAllOf` (query, string | Array, optional) - tag(s) of the video, where all should be present in the video Type: string | Array oneOf: Type: string Type: Array Items: Type: string - `isLocal` (query, boolean, optional) - **PeerTube >= 4.0** Display only local or remote objects Type: boolean - `include` (query, integer, optional) - **Only administrators and moderators can use this parameter** Include additional videos in results (can be combined using bitwise or operator) - `0` NONE - `1` NOT_PUBLISHED_STATE - `2` BLACKLISTED - `4` BLOCKED_OWNER - `8` FILES - `16` CAPTIONS - `32` VIDEO SOURCE Type: integer enum: [0,1,2,4,8,16,32] - `hasHLSFiles` (query, boolean, optional) - **PeerTube >= 4.0** Display only videos that have HLS files Type: boolean - `hasWebVideoFiles` (query, boolean, optional) - **PeerTube >= 6.0** Display only videos that have Web Video files Type: boolean - `host` (query, string, optional) - Find elements owned by this host Type: string - `autoTagOneOf` (query, string | Array, optional) - **PeerTube >= 6.2** **Admins and moderators only** filter on videos that contain one of these automatic tags Type: string | Array oneOf: Type: string Type: Array Items: Type: string - `stateOneOf` (query, id | Array, optional) - **PeerTube >= 8.2** **Admins and moderators only** filter on videos that have one of these states Type: id | Array oneOf: Reference: [id](https://sourcey-peertube.pages.dev/api-rest-reference/models/id.md); Type: id The video state: - `1`: Published - `2`: To transcode - `3`: To import - `4`: Waiting for live stream - `5`: Live ended - `6`: To move to an external storage (object storage...) - `7`: Transcoding failed - `8`: Moving to an external storage failed - `9`: To edit using studio edition feature - `10`: To move to the file system - `11`: Moving to the file system failed - `12`: Import failed - `13`: To duplicate, the files of another video are being copied - `14`: Duplication failed, the files of the other video could not be copied - `15`: The studio edition of a video saved as a new video failed enum: [1,2,3,4,5,6,7,8,9,10,11,12,13,14,15] Type: Array Items: Reference: [id](https://sourcey-peertube.pages.dev/api-rest-reference/models/id.md); Type: id The video state: - `1`: Published - `2`: To transcode - `3`: To import - `4`: Waiting for live stream - `5`: Live ended - `6`: To move to an external storage (object storage...) - `7`: Transcoding failed - `8`: Moving to an external storage failed - `9`: To edit using studio edition feature - `10`: To move to the file system - `11`: Moving to the file system failed - `12`: Import failed - `13`: To duplicate, the files of another video are being copied - `14`: Duplication failed, the files of the other video could not be copied - `15`: The studio edition of a video saved as a new video failed enum: [1,2,3,4,5,6,7,8,9,10,11,12,13,14,15] - `privacyOneOf` (query, VideoPrivacySet, optional) - **PeerTube >= 4.0** Display only videos in this specific privacy/privacies Type: VideoPrivacySet privacy id of the video (see [/videos/privacies](#operation/getVideoPrivacyPolicies)) Schema: [VideoPrivacySet](https://sourcey-peertube.pages.dev/api-rest-reference/models/videoprivacyset.md) enum: [1,2,3,4,5] - `excludeAlreadyWatched` (query, boolean, optional) - Whether or not to exclude videos that are in the user's video history Type: boolean - `startDate` (query, string, date-time, optional) - Get videos that are published after this date Type: string, date-time - `endDate` (query, string, date-time, optional) - Get videos that are published before this date Type: string, date-time - `originallyPublishedStartDate` (query, string, date-time, optional) - Get videos that are originally published after this date Type: string, date-time - `originallyPublishedEndDate` (query, string, date-time, optional) - Get videos that are originally published before this date Type: string, date-time - `durationMin` (query, integer, optional) - Get videos that have this minimum duration Type: integer - `durationMax` (query, integer, optional) - Get videos that have this maximum duration Type: integer 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