--- title: "Search Videos" method: GET path: "/live/{platform}/search/videos" tags: ["Live Data"] --- # Search Videos `GET /live/{platform}/search/videos` ## Request - Base URL: `https://viral.app/api/v1` - URL: `https://viral.app/api/v1/live/{platform}/search/videos` - Auth: API key in header `x-api-key` Searches videos on a platform by keyword. `query` and `pageToken` work the same on every platform. `region` and `language` are hints: applied where a platform's search supports them and ignored elsewhere. The filters of a search route (`sortBy`, `dateRange`, `accountType`) change which results come back, so a platform that cannot apply one refuses the request with a validation error instead of ignoring it. | Platform | Finds | Pages | Applies | Counts in a result | | --- | --- | --- | --- | --- | | TikTok | videos | paged | `region`, `sortBy`, `dateRange` | views, likes, comments, shares, saves | | Instagram | Reels | paged | | views, likes, comments, shares, saves | | YouTube | Shorts | paged | `region`, `language`, `dateRange` | views | | Facebook | videos and reels | paged | | views, rounded for some searches | | Snapchat | Spotlight videos | one page of up to 24 | | views, likes, comments, shares | `dateRange` has one set of values. A platform supports the periods its own filter has and refuses the others: | `dateRange` | TikTok | YouTube | Instagram, Facebook, Snapchat | | --- | --- | --- | --- | | `hour` | refused | yes | refused | | `day` | yes (the last 24 hours) | yes (today) | refused | | `week` | yes | yes | refused | | `month` | yes | yes | refused | | `3-months`, `6-months` | yes | refused | refused | | `year` | refused | yes | refused | | `all-time` | yes | yes | refused | Examples: - `GET /live/tiktok/search/videos?query=ugc&sortBy=likes&dateRange=week®ion=US` - `GET /live/youtube/search/videos?query=ugc&dateRange=month&language=en` - `GET /live/instagram/search/videos?query=ugc` - `GET /live/snapchat/search/videos?query=fitness` - `GET /live/youtube/search/videos?query=ugc&dateRange=6-months` is refused with 400: "dateRange "6-months" is not supported for YouTube. Supported: hour, day, week, month, year, all-time." - `GET /live/instagram/search/videos?query=ugc&sortBy=likes` is refused with 400: "sortBy is supported for TikTok only." A YouTube result without `dateRange` has an id, title, thumbnail and a rounded view count; with `dateRange` it also has the channel, the exact view count, the day of publishing and the length. A Facebook result's publish date is exact to the day, or null where Facebook shows only an age. Snapchat results that mention none of the query's words are left out. A `pageToken` on a platform that has one page returns an empty page and is not charged. Optional live endpoint. You do not need this endpoint for normal API integrations; prefer tracked accounts, tracked videos, analytics, projects, and Creator Hub endpoints when working with viral.app data. ⚠️ Consumes extra credits: 3 credits per request. Additional charges may apply. Headers: - X-Viral-Credits-Consumed - X-Viral-Credits-Meter - X-Viral-Credits-Benefited-Remaining - X-Viral-Credits-Can-Purchase-Extra - Retry-After (on 429 responses) A page past the only one of a one-page lookup costs nothing: it carries X-Viral-Credits-Consumed: 0 and X-Viral-Credits-Meter, without the two balance headers. ## Path parameters - `platform` 'facebook' | 'instagram' | 'tiktok' | 'youtube' | 'snapchat', required: Social media platform (facebook, instagram, tiktok, youtube, snapchat) ## Query parameters - `query` string, required: Search query string - `pageToken` string, nullable: Opaque cursor token used to fetch the next page - `region` string, nullable: Region code (2-letter ISO country code) - `language` string, nullable: Language code for localized search results (BCP 47 style) - `sortBy` 'relevance' | 'date' | 'likes', nullable: TikTok only: order of the results, `relevance` (the default), `date` or `likes`. Refused on other platforms. - `dateRange` 'hour' | 'day' | 'week' | 'month' | '3-months' | '6-months' | 'year' | 'all-time' | 'today' | 'yesterday' | 'this-week' | 'this-month' | 'last-3-months' | 'last-6-months', nullable: Only videos published within this period: `hour`, `day`, `week`, `month`, `3-months`, `6-months`, `year` or `all-time`. TikTok supports `day`, `week`, `month`, `3-months`, `6-months` and `all-time`; YouTube supports `hour`, `day`, `week`, `month`, `year` and `all-time`. A period a platform does not support is refused, and so is any value on Instagram, Facebook and Snapchat. The older names `today`, `yesterday`, `this-week`, `this-month`, `last-3-months` and `last-6-months` are still accepted. ## Response `200` OK - object - `videos` object[], required - `platform` 'facebook' | 'instagram' | 'tiktok' | 'youtube' | 'snapchat', required: Social media platform (facebook, instagram, tiktok, youtube, snapchat) - `platform_video_id` string, nullable, required: Native platform video id found in the URL of the video - `platform_account_id` string, nullable, required: Native platform account id - `account_username` string, nullable, required - `account_display_name` string, nullable, required - `account_profile_picture_url` string, nullable: URL - `region` string, nullable: Region code (2-letter ISO country code) - `caption` string, nullable, required - `hashtags` string[] - `content_type` 'video' | 'slideshow', nullable, required: Filter by content types (video, slideshow) - `video_index` integer, nullable, required - `thumbnail_url` string, nullable: URL - `download_url` string, nullable: URL - `music_id` string, nullable, required - `music_title` string, nullable, required - `music_artist` string, nullable, required - `music_album` string, nullable, required - `music_play_url` string, nullable: URL - `image_urls` string[] - `music_cover_url` string, nullable: URL - `is_original_music` boolean, nullable, required - `duration_seconds` number, nullable, required - `view_count` integer, nullable, required - `like_count` integer, nullable, required - `comment_count` integer, nullable, required - `share_count` integer, nullable, required - `bookmark_count` integer, nullable, required - `engagement_rate` number, nullable, required - `published_at` string, date-time, nullable, required - `nextPageToken` string, nullable, required ## Other responses - `400`: 400 - `401`: 401 - `402`: 402 - `403`: 403 - `404`: 404 - `408`: 408 - `429`: 429 - `500`: 500 - `502`: 502 --- [API](https://skmtc.dev/viral/apis/viral-app-api.md) · [All operations](https://skmtc.dev/viral/apis/viral-app-api/llms.txt) · [OpenAPI document](https://skmtc.dev/viral/apis/viral-app-api/revisions/31e97fa79ef1?raw)